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PREFACE 


This manual is designed as a reference for Wang VS BASIC Version 
3.4.2. The manual is divided into two parts. Part 1 contains 
general discussions of the form of programs and data, and of the use 
of the different types of VS BASIC statements. Chapters 7 and 8 
discuss file, printer, and workstation input and output in the VS 
environment. These discussions generally assume minimal programming 
knowledge. 


Part II contains the specific syntax for each VS_ BASIC 
instruction. Clarifying examples are provided, along with details 
of the required formats. 


The discussions of the following topics in the indicated manuals 
may be helpful to users of this reference manual. 


Topic Manual Part Number 
Command Processor VS_ Programmer's Introduction 800-1101PI 
functions 

EDITOR, LINKER, and VS Program Development Tools 800-1307PT 
Symbolic Debugger 

Procedures and VS_ Procedure Language 800-—-1205PR 
return codes Reference 

Data type formats VS Principles of Operation 800-—1100P0 
DMS and file VS Operating System Services 800-11070S 
structure 

WP files VS Programmer's Guide to VS/IIS 800-1304PW 
System Utilities VS System Utilities Reference 800-1303UT 
File Management VS File Management Utilities 800-1308FM 
Utilities Reference 

COBOL VS COBOL Reference 800-1201CB 
PL/I VS PL/I Language Reference 800-1209PL 
FORTRAN VS_FORTRAN Language Reference 800-1208FM 
RPG II VS RPG II Language Reference 800-1203RP 
Assembly language VS Assembly Language Reference 800-1200AS 
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Description/New Feature 


Version 3.4.2 of BASIC supports 
float decimal numerics. The 
float decimal representation 
allows the programmer to 
perform precise floating-point 
operations. 


These subroutines enable a 
program to interconvert float 
binary and float decimal 
variables. 


Three new error messages, 124, 
448, and 449, have been added. 


The description of the VS EDITOR 
has been updated to reflect the 
current release. 


The restriction prohibiting 
concatenation in an expression 
in REWRITE and WRITE statements 
is described. 


A glossary that defines certain 
BASIC and data processing terms 
has been added. 


The Index has been updated. 
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CHAPTER 1 
INTRODUCTORY CONCEPTS 


1.1 AN OVERVIEW: BASIC ON THE WANG VS 


Wang VS BASIC is a compiled, general-purpose, high-level 
programming language developed by Wang Laboratories, Inc., for use on 
the VS System. This modified version of the original Dartmouth BASIC 
offers all of the original language's important features, as well as 
added capabilities that suit it for both technical and commercial 
applications. Although VS BASIC is extremely powerful and versatile, 
it is also easily learned by beginning programmers because: 


e BASIC statements closely resemble the English language and 
thus give beginning programmers clues to the BASIC meaning. 
In situations where formulae must be used, the BASIC 
language resembles standard algebraic notation and other 
programming languages such as FORTRAN. 


@ A programmer does not need to know much about BASIC to write 
a simple program. The programmer need not learn about the 
advanced capabilities of BASIC until a specific need for 
those capabilities arises. 


VS BASIC incorporates diverse features that aid in program 
development and increase data processing versatility, including: 


@ Variable names up to 64 characters long -- Long variable 


names enable the programmer to assign mnemonic’ and 
self-explanatory names. Programs using such variable names 
are easier to read and debug than are the limited 
two-character names found in most BASIC implementations. 


@ Alphanumeric statement labels -- Any statement in a VS BASIC 
program can be identified by an arbitrary statement label up 
to 64 characters long, which can be referenced in any program 
branch statement (GOTO, IF...THEN...ELSE, etc.). Programs 
can thus be written without regard to line numbers, as is 
necessary in most BASIC implementations. Blocks of program 
code can be given mnemonic labels that indicate their 
function, again increasing program readability and ease of 
debugging. 


e Workstation, file, and printer I/O statements -~- The ACCEPT 
and DISPLAY statements enable BASIC programs to make full use 


of the capabilities of the VS workstation, allowing 
sophisticated screen formatting and use of Program Function 
(PF) keys for data entry and program control. The FMT and 
Image (%) statements allow precise control over format of 
file and printer I/O. 


© Integer and floating-point formats -- Numeric data can be 


stored and manipulated in either format. Use of integer 
format can increase both the speed and efficiency of memory 


use. 
e Float decimal support -- BASIC programs running on all VS 


systems except the VS-50 and VS-80 can perform floating-point 
operations in the float decimal rather than the float binary 
representation. Float decimal operations avoid the 
inaccuracies introduced into calculations when float binary 
values are converted to hexadecimal equivalents. 


e Alphanumeric operations -- Extensive facilities for the 
manipulation of alphanumeric data are provided. Substrings 
can be extracted from strings of characters, and strings can 
be concatenated (put together) or searched for particular 
substrings. 


@ Boolean logic functions on binary values -- All 16 Boolean 


functions of two variables are available in VS_ BASIC. 
Results can be used in alphanumeric expressions or output as 
hexadecimal numbers or ASCII character strings. 


& Intrinsic and user-defined functions -- A full set of 
arithmetic and trigonometric functions is provided by VS 
BASIC. In addition, the programmer can define and name any 
arbitrary numeric function to:-be- used in a program. 


@e Multilingual subroutines -~ Programs written in VS BASIC can 
call subroutines written in other languages (e.g., COBOL, 
PL/I, and Assembly language) and vice versa. 


1.2 COMMUNICATING WITH THE VS 
1.2.1 The Workstation 


The principal means of user communication with the VS is through 
the VS workstation. The workstation is a terminal consisting of a 
Cathode Ray Tube (CRT) display screen and a typewriter-like keyboard. 
The screen displays output from the computer and text typed by the 
user on the keyboard. 


In addition to the keys that correspond to the alphabetic and 
numeric characters that appear on the screen, the keyboard has 16 
Program Function (PF) keys. By using the SHIFT Key, a total of 32 
PF key values can be obtained. 
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Whenever the workstation is ready to accept input from either the 
keyboard or the PF keys, a cursor is shown on the screen. The cursor 
appears as a flashing bar under the character position where the next 
character typed will appear. The cursor (and thus the position of 
the next character) can be moved with the four cursor control keys, 
each of which is marked with an arrow indicating the direction in 
which it moves the cursor. 


At any time, certain keys are accepted for input, while others 
are not. For example, a program may prompt the user to input certain 
numeric data. In this case, the use of the alphabetic keys is 
invalid. Any time an invalid key is pressed, either from the 
keyboard or the PF keys, the workstation alarm sounds, and the key 
is ignored. 


1.2.2 Use of PF Keys: Menus 


Most commands and options entered by the user to system programs 
are entered by means of the PF keys in response to menus. A menu is 
a list of possible commands or options displayed on the workstation 
screen by a program. Next to the description of each command is the 
number of one of the PF keys. Commands are selected by pressing the 
appropriate PF key. 


Communication through PF key response to menu screens is 
extensively used in VS system programs since it frees the user from 
the necessity of typing many commands and remembering’ their 
syntactical arrangements. This allows programs to be highly 
interactive and self-—documenting. 


PF keys can also be used by BASIC programs to control the 
sequence of program execution and to assign values to variables in 
the program (refer to Subsections 6.4.3 and 7.5.3 for details). 


1.2.3 Logging On 


Before using the VS system, the user must log on to the system 
by entering a valid user ID and password at the workstation. User 
IDs and passwords are assigned to authorized users by the system 
security administrator at each VS installation. When the logon 
procedure is completed, the Command Processor is displayed. 


1.2.4 The Command Processor 


The Command Processor is the program that runs whenever no other 
system or user program is executing. When a user first logs on 
(unless a logon procedure runs a program) and whenever any program is 
completed (or interrupted with the HELP key), the Command Processor 
is displayed on the workstation screen. From this menu, the user can 
run a program; examine and manage files, libraries, and volumes 
(refer to Subsection 1.3.2); examine the status of peripheral 
devices; or perform a variety of other functions. 
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1.3 THE VS OPERATING SYSTEM 


The VS Operating System consists of a set of programs that manage 
the hardware and software resources of the VS. The operating system 
allocates processor time and memory space to user tasks, processes 
all input/output operations between user programs and disk or tape 
files, and maintains a security system to ensure that only authorized 
users can gain access to the system hardware, software, and data. 
The operating system also includes the Command Processor, language 
compilers (e.g., BASIC, PL/I, and COBOL), such program development 
aids as the EDITOR and LINKER, File Management Utilities, and various 
other utility programs. The programs that are supplied as part of 
the operating system are called system programs (as distinguished 
from those written by users, called user programs). 


1.3.1 The Data Management System (DMS) 


The Data Management System (DMS) consists of several programs 
that are part of the VS Operating System, and that process all 
input/output transactions between user or system programs and data 
stored in files on magnetic disk or tape. DMS also controls the 
creation of new files. The operation of DMS is transparent in that 
the user does not directly interact with DMS. When a user program 
is running and needs to perform a file I/O operation, DMS is 
automatically called to perform the necessary operations; the user 
program then continues executing with no direct involvement in the 
I/O operation. Many of the functions performed by DMS involve the 
complex internal housekeeping tasks required to insure’ that 
information stored in files remains properly organized for reliable 
and efficient access through all input/output operations. Refer to 


the VS Operating System Services for details on DMS. 
1.3.2 File Hierarchy 


A file is a collection of data stored on either magnetic disk or 
tape, and identified by a file name. Groups of disk files are 
organized into a hierarchical structure with two higher levels: 
libraries and volumes. Groups of tape files are organized into 
volumes (there are no tape libraries). 


The most comprehensive unit in the file management hierarchy is 
the volume. A volume is an independent physical storage medium, 
such as a diskette, disk pack, or tape. The volume name provides a 
device-—independent means of identifying physical storage units. 
Once a diskette, disk pack, or tape has been assigned a volume name, 
it can be mounted at any available drive unit and accessed by name, 
without reference to the address or physical characteristics of the 
disk or tape unit itself. 


Immediately below the volume in the disk hierarchy is_ the 
library. A volume can contain one or more user libraries, but a 
single library cannot continue onto a second volume. Each library 
contains one or more files (every disk file must be assigned to a 
library). The VS places no particular restrictions on the types of 
files placed in a library; a single library can be used for program 
and data files, or special libraries can be designated for each file 
type. The conventions governing library usage are completely 
determined at each individual installation, based on its particular 
needs and standards. 


Duplicate file names cannot be used within the same library, but 
they can be used in different libraries. Similarly, duplicate 
library names are not permitted on the same volume, but can be used 
on separate volumes. Duplicate volume names are allowed but not 
recommended. 


File and library names can contain up to eight characters. 
Volume names contain up to six characters. Each name must begin 
with an uppercase letter, a number, or one of the special characters 
$, #, or @; subsequent characters can be any alphanumeric character, 
including the special characters. Embedded spaces are not allowed. 


1.4 BASIC PROGRAM DEVELOPMENT 


The VS Central Processing Unit (CPU) hardware, like most digital 
computers, can directly execute only instructions written in machine 
language. Machine language consists of groups of electrical impulses 
represented as binary or hexadecimal (base 16) numbers. Machine 
language is cumbersome for programmers, and uSing it to program 
directly is tedious. 


VS BASIC, on the other hand, is an extremely convenient and 
readable language in which to write programs, but the CPU cannot 
directly execute programs written in BASIC. In order for a BASIC 
program to be executed (or "run"), it must first be translated into 
machine language. This translation is accomplished by a large 
program called the BASIC compiler; the translation process is called 
compilation. 


The VS BASIC compiler takes as input a file containing a program 
written in the VS BASIC language as described in this manual. Such 
a program is called a source program; the file containing it is a 
source file. As output, the compiler produces a file containing the 
machine language translation of the source program. This machine 
language program is called an object program; it is contained in an 
object file. The object program can be run using the RUN command 
(PF1) of the Command Processor. 


Development and execution of a VS BASIC program thus consists of 
three steps (not including the logical design and coding of a 
program into BASIC instructions): 


1. The BASIC source program is entered from the workstation 
using the EDITOR utility and is stored in the source file. 


2. The BASIC compiler compiles the source program to produce an 
object program, and the result is stored in the object file. 


3. The object program is run from the Command Processor. 


These steps can be performed separately by running first the 
EDITOR, then the BASIC compiler, and finally the user's object 
program, returning to the Command Processor after each step. The 
entire process can also be performed from the EDITOR, enabling the 
user to compile and run programs directly from its Special Menu. 
The EDITOR is described in detail in Subsection 1.4.1, and in the VS 
Program Development Tools; the process of creating and running a new 
BASIC program is summarized in Subsections 1.4.1 and 1.4.2. 


1.4.1 The EDITOR 


To run the EDITOR, invoke the RUN command (PF1) from the Command 
Processor, type EDITOR for the program name, and key ENTER. 


The EDITOR first displays an Input Definition screen, requesting 
the following information: 


LANGUAGE -- Type B or the word BASIC. 


source FILE, LIBRARY, VOLUME -- If a new file is to be created, 
leave the file name blank. Names are assigned to new files 
after the text of the file has been entered, with the CREATE 
command (PF5). If an existing file is to be edited, enter its 
name, and the names of the library and volume on which it is 
contained. LIBRARY and VOLUME may have default values set when 
this screen appears. These can be changed by typing over the 
default responses. 


Object PLIBRARY, PVOLUME -- Specify the library and volume names 
for any object program generated in this session. Note that no 
permanent object file is created until a permanent source file 
is compiled. PLIBRARY and PVOLUME may have default values 
(corresponding to OUTLIB and OUTVOL, respectively) set when this 
screen appears; these values can be changed by typing over the 
default responses. 


Print File LLIBRARY, LVOLUME -- Specify the library and volume 


names for compiler-generated print files. These fields default 
to SPOOLIB and SPOOLVOL, respectively, but can be modified. 
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Debug DLIBRARY, DVOLUME -- Specify the library and volume names 
for symbolic debug information files. DVOLUME defaults to the 
user's current OUTVOL value; the default value for DLIBRARY is 
generated by concatenating the user ID with DEBUG. These values 
can be modified by typing over the default responses. 


SCRATCH -- Specify whether the EDITOR should automatically 
delete a file having the same name and location as a compilation 
output file. The default response, YES, automatically scratches 
the existing file; a NO response causes the EDITOR to request 
another file location or permission to delete the file. 


When all of the above information has been typed in appropriately, 
press ENTER. 


The EDITOR next creates a work file for text editing. The 
editing of source text actually takes place in this temporary work 
file. In order to permanently store any text entered in the EDITOR, 
the user must either create a new file of the edited text or, if an 
old file was used, replace the old text with the edited text. The 
original file is not altered until a replace is done, as all changes 
are made in the work file. Files are created and replaced with the 
CREATE (PF5) and REPLACE (PF6) commands from the EDITOR's Special 
Menu. 


The EDITOR then displays its normal menu, which contains 
functions for examining, entering, and editing source text. The 
most important functions are briefly explained here. More detail on 
these and explanations of the other functions can be found in the VS 


Program Development Tools. 


PF1 -— DISPLAY -- Display mode displays the user's file on the 
screen. The first time this command is used in an EDITOR session 
on an existing file, the file is displayed starting with the 
first line of text. Subsequent uses of this command return to 
displaying the file at the point where the last editing function 
was performed. While in display mode, different portions of the 
file can be examined by using PF keys 2 through 6. 


PF9 — MOD --— Modify mode allows the user to enter a new program, 
modify existing source lines, or add lines to the end of an 
existing program. 


PF1l -—- INS -- Insert mode allows text to be inserted in an 
existing program between lines, before the beginning of the 
program, or at the end. The user can also enter a new program 
in insert mode. Unlike the modify mode, the line numbers 
supplied by the EDITOR can be altered in place, if the user 
wishes. Before pressing PF1ll, the cursor should be positioned 
on the line after which the new line is to be inserted. 


PF12 — DEL -—- Delete mode allows the user to delete text (either 
a specific line, a range of lines, or all lines) from the source 
file. Before pressing PF12, the cursor should be positioned on 
the first line to be deleted. 


PF16 — MENU -- Activates the EDITOR's Special Menu. 


To enter lines of text for a new file, enter either modify (PF9) 
or insert (PF11) mode and simply type in the lines. Pressing ENTER 
sends the lines that were just typed to the system for processing. 
This must be done after every inserted line. In modify mode, the 
screen can be filled with new lines before ENTER is pressed. 


In order to return to display mode from modify or insert modes, 
press PFl after the last line of text is entered (or, if in modify 
mode, press ENTER after typing in no new lines of text). 


When the entire BASIC program has been entered, it can be stored 
in a disk file, compiled, or run directly. All of these functions 
are performed from the EDITOR's Special Menu. The Special Menu is 
obtained by pressing PF16 from display mode. 


The Special Menu has 14 functions; the most important ones are 
listed below. These functions, as well as those not described here, 


are described in detail in the VS Program Development Tools. 


PF1l -— DISPLAY -- The EDITOR is returned to the point in text 
editing from which the Special Menu was invoked. 


PF5 -— CREATE -— A new file of the edited text is generated. The 
user is asked to supply file, library, and volume names and 
several optional pieces of information, including a retention 
period during which the file cannot be scratched. 


PF6 — REPLACE -- The old input file is replaced with the new 
edited text. 


PF9 -— RUN -—- An uncompiled program is compiled and run, or a 
compiled program is run. If the text has not already been 
successfully compiled in this EDITOR session since the last text 
entry was made, RUN invokes the BASIC compiler and LINKER to 
compile the program, and then automatically runs the program 
(unless there are serious compilation errors). If compilation 
is not necessary, the program is run. 


PF10 — COMPILE -- The BASIC compiler and (optionally) the LINKER 
utility are invoked, but the program is not actually run. 


PF11 — ERRORS -- A list of detected errors is displayed. If the 
default value of ERRLIST in the Compiler/LINKER Options display 
was changed to NO, this list is not displayed, and is not 
accessible from the EDITOR. 


PF16 —- EOQJ -- EDITOR processing is ended and control is returned 
to the Command Processor. 


NOTE 


The user must specify an object file name, library, and 
volume whenever a permanent source file is compiled from 
the EDITOR, and PLIBRARY and/or PVOLUME were not set 
previously. If PLIBRARY and PVOLUME have been set, 


BASIC uses the file name of the source file as the file 
name of the object file. Specifying a file name that 
begins with ## causes a temporary file to be created. 
Such a file is automatically scratched at the end of the 
EDITOR session. 


1.4.2 The BASIC Compiler 


The BASIC compiler can be invoked either from the Command 
Processor by the RUN (PF1) command, or from the EDITOR by the RUN 
(PF9) or COMPILE (PF10) commands on the Special Menu. [In either 
case, the compiler displays a list of options when it is invoked. 


Options 


The compiler options are described in detail in Appendix B. The 
four most important options are: 


LOAD -- Directs the compiler to produce an object program as 
output. Its default value is YES. If NO is typed, no object 
program is produced. (The code generation phase of the compiler 
is not run.) 


SOURCE -- Directs the compiler to produce a listing of the 
source code for the compiled program combined with a list of any 
compiler-detected errors. YES causes the listing to be 
produced, while NO suppresses it. The default value is YES. 


SYMB -- Directs the compiler to insert symbolic debug 
information into the object program, permitting subsequent use 
of the VS interactive symbolic debug facility when the program 
is run. Symbolic debug information can be removed from a 
program with the LINKER utility. The default value is YES. 


DFLOAT -- Directs the compiler to perform all floating-point 
manipulations in the float decimal representation. A response 
of YES causes float decimal handling; the default response of NO 
causes float binary handling. Because the decimal 
floating-point format is not available on the VS-80 or VS-50, a 
response of YES on these machines results in an immediate error 
message. 


When all desired options have been selected, press ENTER. 
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Input Definition 


The BASIC compiler now requests the name of the source file to be 
used as input, unless BASIC was invoked from the EDITOR. Enter the 
file name, along with the appropriate library and volume names. 


Output Definition 


If LOAD = NO was specified, and if the program passes the 
compiler's syntax check with no error of severity equal to or greater 
than the specified STOP level (see Appendix B), a name for the output 
file to be created containing the compiled (object) program is 
requested. Enter the file name, along with the names of the library 
and volume to which it will be assigned. The following options can 
also be specified: 


RECORDS -- The number of records in the output file is 
determined automatically by the compiler based on the size of 
the input file. In general, this value should not be changed by 
the user. 


RETAIN -—- During the specified retention period, the file cannot 


be scratched or _ renamed. Only the owner or a= security 
administrator can change the retention period. If such 
protection is not deemed necessary, the RETAIN field should be 
left blank. 


RELEASE --— If RELEASE=YES, any space originally allocated to the 
object file but not actually used is released for use by other 
files. Otherwise, the space remains reserved for use by the 
object file. 


FILECLAS -- The object file may be assigned to one of the VS 
file protection classes. Consult the system security 
administrator to determine in which protection class a 
particular file belongs. 


When the output file name and all options are defined, press 
ENTER. The message "BASIC Compilation of X in Progress" appears on 
the screen while the compiler runs from the EDITOR; the message 
"Program BASIC in Progress" displays if BASIC is run directly from 
the Command Processor. When compilation is complete, control returns 
to either the Command Processor or the EDITOR, depending on how the 
compiler was initially invoked. 


Return Code 
When compilation is complete, the first screen shown specifies a 
return code. The value of the return code indicates the severity of 


the errors found by the BASIC compiler in the source program. The 
possible return codes and their meanings are: 
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Code Meaning 


0 No errors. 

4 Warning. 

6 or 8 Severe error (program probably will not run 
correctly). 

12 or 16 Terminal error (program will not run at all). 


If production of the source listing was not suppressed, this 
listing and a list of compiler diagnostics (error messages) are 
printed on the selected printer, or directed to the print queue or 
the user's print library as specified by the user's PRNTMODE default 
(set with PF2 from the Command Processor; refer to the VS 
Programmer's Introduction for an explanation). All other optional 
listings and tables are similarly printed, queued, or filed. 


When the BASIC compiler is run from the EDITOR (by either the 
RUN (PF9) or the COMPILE (PF10) commands from the Special Menu), any 
error messages generated during the compilation can be viewed by 
keying PFll from the Special Menu. 


1.4.3 The LINKER Utility 


The VS LINKER is used to perform the following functions: 


1. Link two or more object program modules or subroutines into 
a single executable program (refer to Section 6.5). 


2. Link library subroutines into a main program. 
3. Remove symbolic debug information from an object program. 
4. Replace one or more object program modules in a program. 


The LINKER utility can be called whenever a program is compiled 
from the EDITOR. If the program is compiled using the BASIC 
compiler directly, the LINKER must be run independently by invoking 
the RUN command from the Command Processor and typing in LINKER as 


the program name. See the VS Program Development Tools for more 
information on the LINKER. 


Note that due to changes in the VS Operating System, the user 
cannot link BASIC Version 2.3 programs to BASIC Version 3.2 or above 
programs. The CVBASIC utility converts BASIC Version 2.3 programs 
to BASIC 3.2 programs, and is described in Appendix I. 
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1.4.4 Running the Object Program 


The compiled program is run with the RUN command from the Command 
Processor. Press PFl to invoke this function, and type the BASIC 
object file name in the PROGRAM field. Type the appropriate library 
and volume names, and press ENTER to initiate execution of the 
program. 


The program will continue to run until one of the following 
occurs: 


1. An END statement is executed. 


2. An "implied" END is reached because the physical end of the 
program is reached. 


3. A fatal execution error occurs. 
4. The user interrupts execution with the HELP key. 


Any program can be interrupted at any time with the HELP key. A 
modified Command Processor is then displayed. From this menu, the 
user can cancel or continue to execute a program, enter debug 
processing, or perform other system commands. The Debug Processor is 
a powerful tool used to detect hard-to-find errors in the logical 
design of a program. The Debug Processor is discussed in the 
VS Program Development Tools. The user should note, however, that 
float decimal data currently cannot be examined or modified through 
the Debug Processor. Refer to Section 3.3 for details. 


If a program completes execution without interruption by errors 
or the HELP key, control returns to either the Command Processor or 
the EDITOR, depending upon how execution of the program was 
initiated. 
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CHAPTER 2 
PROGRAM FORMAT 


2.1 INTRODUCTION 


A VS BASIC source program consists of a series of instructions to 
the computer, called statements, which are written sequentially on 
numbered program lines. A program line can contain any number of 
statements. When a program is run, statements are executed 
sequentially in line number order. Multiple statements on the same 
line are executed left to right. 


2.2 STATEMENTS 


A statement usually begins with a word (called a "verb") that is 
typically an English verb, such as PRINT or ACCEPT. Any information 
that may be required to complete that particular statement follows 
the verb. For example: 


RETURN forms a complete statement by itself. It signals the end 
of a subroutine. 


LET X=2 is an example of an assignment statement. In this case, 
the variable X is assigned a value of 2. 


GOTO 40 transfers control to the given line number, and 
continues processing from there. 


IF is a BASIC verb but is not a complete BASIC statement by 
itself. 


IF A=B THEN RETURN shows that another entire BASIC statement may 
follow the IF... verb. The IF statement causes some action to 
be taken depending upon whether or not a particular relation is 
true. 


Verbs form part of a larger set of reserved words. Reserved 
words are sequences of alphanumeric characters that have some 
predefined meaning to the BASIC compiler. Reserved words never 
contain any embedded spaces. Since reserved words and their 
meanings are built-in parts of the BASIC compiler, they cannot be 
used by the programmer as variable names or statement labels (see 
Section 6.2). Appendix A contains a complete list of VS BASIC 
reserved words. 


There are two types of BASIC’ statements: executable and 
nonexecutable. An executable statement specifies some action or a 
series of actions to be taken by the user's program at run time, such 
aS assigning a value to a variable (LET statement), displaying or 
printing data on the workstation or printer (PRINT statement), or 
altering the order of program execution (GOTO statement). A 
nonexecutable statement provides information to the compiler at 
compilation time that may be required to generate the object program, 
such as the amount of storage to be allocated for certain variables 
(DIM statement) or the format to be used for printed output (FMT 
statement). 


The following VS BASIC statements are defined as nonexecutable: 


COM 

DATA 

DEF 

DEF FN' or DEFFN' 

DIM 

EJECT 

FMI or FORM 

% (Image) 

REM or * 

SELECT, when used for file I/O (1.e., SELECT # and SELECT POOL; 
see Subsection 8.3.1 for details) 

SUB 

TITLE 


2.3 LINE FORMAT 


Each line in a VS BASIC program can be up to 72 characters long, 
including leading and embedded spaces (the workstation screen is 80 
characters wide). Each character position is referred to by a column 
number, beginning with column 1 (the leftmost position). The first 
six columns of each line in a BASIC source file are reserved for a 
unique six-digit line number, leaving 66 columns (numbers 7 through 
72) for program statements. Columns 73 through 80 may be used as a 
program identifier. Any line containing an asterisk (*) in column 7 
is designated as a comment line and is ignored by the BASIC compiler 
(see Subsection 2.3.3). 


NOTE 


When the EDITOR is used to create or edit BASIC source 
files, program lines are displayed on the workstation 
screen with an extra space inserted between column 6 
(which contains the rightmost digit of the line number) 
and column 7 (the first column available for typing 
program text characters). This extra space is also 
inserted to increase readability when the BASIC compiler 


prints source file listings. Thus, on printed listings 
and in this manual, the character in column 7 of a line 
actually appears in the eighth physical print position 
on the paper. This extra space is not, however, 
included in the internally stored representation of a 
program line. 


2.3.1 Spacing 


Within a statement, the VS BASIC compiler uses spaces between 
strings of nonblank characters to distinguish the significant 
entities or "tokens" that comprise the statement. To avoid 
ambiguity, spaces must occur at certain places in a statement and 
must not occur at others. For example: 


100 FORK =I TOJ 500 FORK = ITOJ 


Both lines contain the same sequence of nonblank characters, and 
both are valid VS BASIC statements, but with completely different 
meanings. Line 100 is the beginning of a FOR...NEXT loop (see 
entries under FOR and NEXT in Part II). In this statement, FOR and 
TO are VS BASIC reserved words (see Section 2.2) and K, I, and J are 
names of variables. Line 500 is an assignment statement (an 
"implied" LET statement) in which both FORK and ITOJ are variable 
names; the statement assigns the value of ITOJ to the variable FORK. 


In general, spaces should occur in a statement so as to 
eliminate ambiguities in the interpretation of the statement. In 
particular, the following rules should be observed: 


1. All VS BASIC reserved words, including verbs, must be 
spelled exactly as shown in Appendix A, with no embedded 
spaces. GOTO and GO TO are both valid and equivalent forms 
for the unconditional branch statement. GOSUB and GO SUB 
are also both valid and equivalent statements. 


2. Literals (see Subsection 3.4.1) can contain any combination 
of blank and nonblank characters; a literal, however, cannot 
contain its delimiter. 


3. No embedded spaces are allowed within variable names (see 
Subsection 3.3.3 for rules of forming variable names). 
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4. No embedded spaces are allowed within statement labels (see 
Section 6.2 for rules governing formation of statement 
labels). 


5. No embedded spaces are allowed in numbers (either line 
number references or constants). 


6. One or more spaces is required between any reserved word, 
variable name, or statement label and any other reserved 
word, variable name, or statement label. 


7. Spaces are ignored immediately before and after arithmetic 
operators (see Subsection 4.2.2), relational operators (see 
Subsection 4.2.3), and punctuation marks. 


2.3.2 Multiple Statement Lines 


A program line can contain any number of statements. A line 
containing no statements is called a null line and consists simply 
of a line number followed by 74 spaces. If a program line contains 
more than one statement, a colon (:) is used to separate one 
statement from the next, except following Image (%), TITLE, or EJECT 
statements (each of these statements is always considered as 
extending to the end of the line on which it occurs). For example: 


400 LET TWEEDLEDUM=I : LET TWEEDLEDEE=J : LET ALICE$="CONFUSED" 


A null statement can be inserted anywhere in a line by using one 
colon immediately after another, or two colons separated only by 
blanks. 


2.3.3 Continuation of Statements 


Statements can be continued beyond column 72 of a line by 
inserting an exclamation point (!) in column 72 of the line to be 
continued. For example: 


400 LET ROCK= : 
500 4 


is equivalent to: 

400 LET ROCK=4 

Although a statement can begin on one line and end on another 
line, reserved words, constants, variable names (see Subsection 


3.3.3), statement labels (see Section 6.2) and line number references 
cannot be split between lines. For example: 


400 LE ! 
500 T ROCK = 


is not a valid statement. Literal strings (see Subsection 3.4.1), 
however, can be split. 


There is no limit to the number of lines that can be used to 
contain a single statement, nor to the number of statements that can 
occupy a single line. 


2.3.4 Sequence of Execution 


Execution of a BASIC program always proceeds in line number 
sequence from the lowest-numbered line through the highest-numbered 
line, unless the normal sequence of execution is altered by a program 
branch instruction. Program branch instructions include’ the 
following: FOR...NEXT loops, GOTO, GOSUB, GOSUB', CALL, RETURN, and, 
in certain cases, IF...THEN...ELSE. Program branch instructions are 
discussed more fully in Chapter 6 and Part II. 


2.4 PROGRAM DOCUMENTATION 
2.4.1 Comments 


As an aid to program documentation, it is often useful to insert 
explanatory comments into the text of a program. Such comments must 
be distinguished in some way so that the compiler does not attempt 
to interpret them as executable program statements. VS BASIC 
provides three methods of inserting comments into programs. 


1. Any line that has an asterisk (*) in column 7 (the first 
column following the six-digit. line number) is treated as a 
comment line. The entire line is disregarded by the 
compiler and can contain any combination of printing 
characters. Comment lines of this form cannot be continued 
(as described in Subsection 2.3.3). Example: 


100000* DIRAC WAS A QUANTUM MECHANIC 


2. Any statement beginning with the reserved word REM is 
treated as a comment (REMark). REM statements are ignored 
by the compiler and can appear wherever any other statement 
appears (see Section 2.3). A REM statement can contain any 
combination of printing characters except a colon (:). A 
colon is considered to be a statement terminator and can be 
used to separate a REM statement from another statement on 
the same line. REM statements can be continued by the use 
of the exclamation point in column 72, as discussed above. 
Examples: 


100 REM CATASTROPHE THEORY SIMULATION OF CANINE BEHAVIOR 


560 DST=SIN(A)/COS(B) :REM CHECK FLAGS :IF FLAG1=1 THEN 1200 


3. A comment can be inserted by enclosing it between the symbols 
/* and */. Comments delimited in this way (called "enclosed 
comments") can be inserted on a line alone, before, after, or 
between statements on a line, or within a_e statement. 
Enclosed comments within statements can occur before or after 
(but not within) reserved words, variable names, statement 
labels, line number references, numbers, literals, functions, 
operators and punctuation marks. All characters that follow 
the /* symbol (including subsequent occurrences of /*) are 
treated as part of the comment until the */ is encountered. 
Enclosed comments can span multiple lines. Examples: 


700 EXCH$ /* TELEPHONE EXCHANGE */ = STR(PHONENUMBER$, 4,3) 
1100 /* COMMENTS OF THIS FORM MAY EVEN EXTEND 
1200 OVER MANY LINES, AND MAY CONTAIN ANY SERIES 
1300 OF CHARACTERS... !@#$%¢&*()... BUT MUST 
1400 END WITH THE STAR-SLASH SYMBOL: */ 


2.4.2 Compiler Directives 


VS BASIC also lets the programmer use the TITLE and EJECT 
statements to control the pagination and titling of the program 
source listing produced by the compiler. TITLE and EJECT both 
belong to a set of statements known as compiler directives. Lines 
that contain TITLE and EJECT directives are not printed in source 
listiMgs generated by the compiler, although their’ respective 
effects on the form of the listing do appear, as described below. 
TITLE and EJECT lines are, however, shown by the VS EDITOR and file 
display programs. 


A TITLE statement must be the only statement on a line. Whena 
TITLE statement is encountered during compilation, the compiler 
skips to the top of the next page of the output listing and titles 
that page with the line of text specified in the TITLE statement. 
All subsequent pages of the listing are also printed with the 
specified title until another TITLE statement occurs. All characters 
(including any occurrence of a colon (:) or an exclamation point (!)) 
following the reserved word TITLE on the same line are regarded as 
part of the title. Note that this means that a TITLE line cannot be 
continued by use of the exclamation point (!) convention described in 
Subsection 2.3.3. For example, to print the title PART I: VARIABLE 
INITIALIZATION SECTION at the top of a page of source listing, one 
would use 


500 TITLE PART I: VARIABLE INITIALIZATION SECTION 


The EJECT statement, which must also appear as the only 
statement on a line, causes the compiler to skip to the top of the 
next page of the source listing and to print the most recently 
specified title at the beginning of the page. All text following 
the word EJECT on the same line is ignored. 


CHAPTER 3 
DATA FORMATS 


3.1 INTRODUCTION 


Programs written in VS BASIC are capable of processing both 
numeric and alphanumeric data. Numeric data can be stored and 
processed either in integer format or in floating-point format. 
Alphanumeric information can be stored and manipulated as_ single 
characters or as strings of characters. In addition, individual 
bits within alphanumeric data can be manipulated using logical 
operators. 


Both numeric and alphanumeric data can be processed singly, as 
constants or scalar variables, or in sets of arbitrary size called 
arrays, which can be referred to by a single name. Individual 
elements of an array can also be processed as scalar variables. 


This chapter describes the types of data VS BASIC processes and 
the formats used for representing data. The various operations that 
can be performed on data are discussed in Chapters 4 and 5. 


3.2 CONSTANTS, VARIABLES, RECEIVERS, AND EXPRESSIONS 


A constant is an item of data whose value is fixed in a program 
and does not change during program execution. In contrast, a 
variable is an item of data that does not have a fixed value and can 
be assigned different values during program execution. A constant 
appears in a VS BASIC program as a number or a literal (see 
Subsection 3.4.1). Each variable is represented by a_ unique 
variable name that is used to name that area in storage that holds 
the value of the variable. For example, in the statement 


CIRCUMF = 3.14159 * DIAM 


CIRCUMF and DIAM are variable names, and 3.14159 is a constant. 
This particular statement multiplies the value of the variable DIAM 
by the constant 3.14159 (the asterisk (*) is the symbol used to 
indicate multiplication in BASIC) and stores the product in the 
variable called CIRCUMF. The different types of constants and 
variables VS BASIC recognizes and the rules for naming variables are 
described in Subsection 3.3.3. 


A receiver iS a variable into which data can be_ stored. 
Receivers are used wherever a value is "received," e.g., on the left 
side of a LET statement, in the argument list of a READ statement, 
etc. All variables are receivers; for numeric data, all receivers 
are variables. Alphanumeric receivers (or simply "alpha receivers") 
include alphanumeric variables and a few special functions. See 
Subsection 5.4.2 for a list of all alpha receivers. 


An expression is either a constant, a variable, a function, or 
some combination of these connected by operators. When a statement 
containing an expression is executed, the indicated operations and 
functions are performed to yield a single value for the expression. 
Functions and operators are constructs that specify particular 
operations to be performed on one or more expressions. Separate 
operators and functions exist for manipulating numeric’ and 
alphanumeric data, and are discussed in Chapters 4 and 5. An 
expression can contain either numeric or alphanumeric data, but the 
two data types cannot be combined in one expression. 


3.3 NUMERIC DATA 


VS BASIC recognizes two types of numeric data: floating-point 
and integer. The types are clearly distinguished in BASIC syntax, 
require different amounts of internal storage, are represented 
differently in internal format, and have a different range of 
allowable values. In addition, VS BASIC supports two floating-point 
representations: float binary and float decimal. However, the 
float decimal representation is not available on VS-50 and VS-80 
systems. 


Integer data, which is used to represent "whole" (i.e., 
nonfractional) numbers, is stored in four bytes of memory. Thus, 
the integer data type can represent values ranging from 
-2,147,483,648 (-2°') to 2,147,483,647 (2°'-1). 


Float binary data is stored as a hexadecimal fraction between 0 
and 1, a binary exponent of base 16, and a sign. The float binary 
representation requires eight bytes of storage: one byte for the 
sign and exponent, and seven bytes for the fraction. Since a digit 
in the hexadecimal representation requires four bits of storage, 
float binary values can contain up to 14 digits of precision. The 
maximum magnitude for float binary values iS approximately 
7.2 x 10’°; the minimum magnitude is approximately 5.4 x 10°7°. 


Consult the VS Principles of Operation for details on the float 


binary representation. 


Float decimal data (not available on VS-50 and VS-80 systems) is 
stored as a decimal fraction between 0 and 1, a binary exponent of 
base 10, and a sign. The float decimal representation requires 
eight bytes of storage: one byte for the sign and exponent, and 
seven bytes for the fraction. Since a decimal digit requires four 
bits of storage, float decimal values can contain up to 14 digits of 
precision. The maximum magnitude for float decimal values is 
9.9999999999999 x 10°7; the minimum magnitude is 1 x 10°°*. 
Consult the VS Principles of Operation for details on the float 


decimal representation. 


NOTE 


A single module must perform all floating-point 
operations in either the float binary or the float 
decimal representation. The type of representation is 
selected through the DFLOAT compilation option, 
described in Subsection 1.4.2 and Appendix B. If two 
modules with different floating-point representations 


are linked, float data in one module must be converted 
to the other representation before access by the other 
module. The CVDQ and CVQD subroutines, described in 
Part II, interconvert variables in the float binary and 
float decimal representations. If two modules using 
different floating-point representations do not share 
floating-point data, no conversion is required. 


Each type of numeric data has its particular advantages and 
disadvantages. Integer calculations are fast and precise; however, 
integer data cannot represent fractional or very large or very small 
values. Float binary calculations can manipulate a wider range of 
values than the integer or float decimal data type, but lose 
precision in the conversion to and from _ the _ hexadecimal 
representation (refer to Appendix C for more information). Float 
binary calculations are also slower than integer calculations. 
Float decimal calculations can manipulate a wider range of values 
than the integer data type with no loss of precision; however, float 
decimal operations are slower than float binary or integer 
calculations. A program using the float decimal representation is 
also larger than an identical program using float binary values. It 
is up to the programmer to determine the best numeric representation 
for a particular application. 


The user should note that float decimal data currently cannot be 
examined or modified through the Debug Processor Inspect and Modify 
function. However, the hexadecimal value of the float decimal data 
can be examined; consult the VS Principles of Operation for details 
on the hexadecimal format of float decimal data. 


VS BASIC allows complete freedom to mix floating-point and 
integer data (but not float binary and float decimal data) in 
arithmetic expressions and assignment’ statements. Expressions 
containing both integer and floating-point data are called mixed 
mode and are discussed in Section 4.5. 


3.3.1 Floating-Point Constants 


A floating-point constant can be a positive or negative number 
of up to 15 digits. Fifteen digits can be specified for float 
binary constants because the 14 hexadecimal digits of the internal 
representation can evaluate to more than 14 decimal digits; for 
float decimal values, the fifteenth digit is used to round the value 
of the fourteenth digit. The compiler issues a warning when it 
encounters a floating-point constant with more than 15 digits in the 
source program. Only the first 15 digits, excluding leading zeros, 
are used by VS BASIC statements or functions. 


NOTE 


All VS BASIC numeric statements and functions use only 
the first 15 digits of a floating-point number. 
Specifically, truncation to 15 digits occurs (at the 
indicated time) with: 


Any floating-point constant (compile time). 


Any floating-point value that the user enters (1i.e., 
to INPUT, ACCEPT, or READ statements; run time). 


Any floating-point number converted from 
alphanumeric format to floating-point format via 
Image (%), FMT, or CONVERT statements (run time). 


A float binary constant can range from zero or approximately 
+5.4 x 10°’° to +7.2 x 107°; float decimal constants can range 
from zero or approximately +1 x 10°°° to +1 x io’ 


Very large or very small floating-point numbers can be expressed 
in exponential form. Exponential form corresponds to standard 
"scientific notation" in which numbers are written as a decimal with 
one digit to the left of the decimal point, multiplied by some power 
of 10. Since the superscripts needed to write numbers in such 
notation cannot be easily represented on a keyboard device, a number 
in exponential form is represented as a decimal (usually with one 
digit to the left of the decimal point), immediately followed by the 
letter E, followed by an exponent representing a power of 10. The 
exponent must be an integer and can have a sign; if no sign is given 
for the exponent, it is assumed to be positive. Leading zeroes can 
be omitted. Numbers in exponential form contain no embedded spaces 
between the decimal, the letter E, and the exponent. For example: 
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Floating 


Long form Scientific notation point constant 
45000000 4.5 x 10’ 4.5807 
.00000045 4.5 x 107’ 4.5E-7 
37234.123 3.7234123 x 107 3.7234123E+04 


The following are examples of valid floating-point constants in 
BASIC: 


4, -10, 1432443, -7865, 24.4563, -3E2, 2.6E-27 


The following are examples of invalid floating-point constants in 
BASIC: 


8.7E5.8 -- Not valid because of the decimal point in the 
exponent. 
-87E-99 -—- Not valid because it is less than 5.4E-79 (float 


binary) and 1E-66 (float decimal). 


103.2E99 -- Not valid because it is greater than 7.2E75 (float 
binary) and 1E63 (float decimal). 


103.2E70 -—- Not valid in the float decimal representation 
because it is greater than 1E63; valid in the float 
binary representation. 


3.3.2 Integer Constants 


An integer constant can range from ~-2,147,483,648 to 
2,147,483,647 (the decimal equivalent of the range of binary numbers 
that can be represented with 32 bits) and must, as its name 
indicates, be an integer. An integer constant is denoted by a "%" 
following the constant. Thus, "4%" is an integer, and "4" is a 
floating-point number. The percent sign for numeric constants is 
only permitted for numbers or variables actually contained in the 
source file. Therefore, numbers given to the program during 
execution (i.e., from the workstation or data file, or converted 
from an alpha expression) must be given in floating-point form 
(i.e., without the percent sign). 


3.3.3 Numeric Variables 


Numeric variables are used to reference numeric data stored in 
memory. Unlike constants, variables can be assigned new values 
during execution by a variety of different statements. Each 
variable name in a program is associated with an area in memory used 
to contain the value of that variable. Numeric variables are 
initialized to zero by the compiler. 


3-5 


As is the case with constant data values, VS BASIC processes 
scalar variable values as_ either integers or floating-point 
numbers. All scalar floating-point variables are eight bytes in 
length, while all scalar integer variables are four bytes in length. 


Within the floating-point and integer data types, VS _ BASIC 
variable numeric data can be referred to as either scalar variables 
or array variables. The two kinds of variables differ in the syntax 
rules that apply to them and in their storage requirements. A 
numeric scalar variable contains a single numeric value. An array 
variable, on the other hand, contains one or more values, or 
"elements," all of which can be referenced by a single name and 
which can be manipulated either collectively or individually. Array 
variables are discussed more fully in Section 3.5. 


It is important to note the differences between integer and 
floating-point calculations. Refer to Section 3.3 and Appendix C 
for details. 


Each variable in a program is referred to by an arbitrary and 
unique variable name chosen by the programmer. A variable name can 
be any string of up to 64 letters, digits, and underscores, provided 
that the first character is a letter and that the string is not a VS 
BASIC reserved word (see Section 2.2 and Appendix A). Numeric 
variables are designated as integer data type by appending a percent 
sign (%) to the end of the variable name. Any numeric variable that 
does not have "%" as the last character of its name is treated as a 
floating-point variable. The following are examples of valid numeric 
variable names: 


Floating-point Integer 

N N% 

CAT MOUSE% 

PART 2 FIRST 3 LINES% 


The following are examples of incorrect variable names: 


Variable Name Reason 
2ND_ PART The first character must be a letter. 
LINE COUNT% Names cannot contain spaces. COUNT% alone is 


a legal variable name. 


LAST %ILE "%" is legal only at the end of a variable 
name. 


3-6 


Note that a floating-point variable name and an integer variable 
name always identify different variables, even if the names are 
identical exclusive of the percent sign (%) (i.e., the letters, 
digits, and underscores). For example, INFUNDIBULUM and 
INFUNDIBULUM% identify two different variables, one floating-point 
and one integer, and both can be used to refer to different items of 
data in the same program without ambiguity. 


3.4 ALPHANUMERIC DATA 


In addition to its ability to manipulate and operate upon numeric 
data, VS BASIC also provides the capability of processing information 
in the form of alphanumeric character strings. A character string is 
a sequence of characters treated as a unit. A character string can 
consist of any sequence of keyboard characters, including letters A 
through Z, digits 0 through 9, and special symbols. Character 
strings are represented in a program as literal strings (the 
alphanumeric equivalents of numeric constants), or as the values of 
alphanumeric string variables. Characters not found on the keyboard 
can be represented as hexadecimal ASCII codes. Typical examples of 
uses of character strings are names, addresses, and report headings. 


Note that alphanumeric data cannot be operated upon by numeric 
functions or operators. A separate set of operators and functions 
exists for the manipulation of alphanumeric data. VS BASIC also 
provides functions that convert alphanumeric data to numeric form 
and vice versa; refer to Section 9.1 for details. 


3.4.1 Literals (Alphanumeric Constants) 


The value of an alphanumeric data item that is a fixed constant 
in a source program is called a literal or a literal string. A 
literal string can be written either by enclosing the desired 
sequence of characters in quotation marks or by specifying the 
hexadecimal ASCII codes of the characters in the literal with the 
HEX function. 


One type of quoted alphanumeric literal string is a sequence of 
1 to 255 characters enclosed in double quotation marks ("..."). Any 
upper— or lowercase keyboard character except the double quote 
character can appear in a double-quoted literal. Literal strings 
can be used to specify messages, headings, or titles to be output to 
some device (e.g., workstation or printer) by any of several output 
statements. For example, 


PRINT "Last Page="; LPG 
In this case, Last Page= is a quoted literal that would be printed 


exactly as it appears. LPG is the name of a floating-point variable 
whose value would be printed following Last Page=. 


A second type of quoted literal string is available for 
specifying lowercase characters. The literal string is entered with 
upper- or lowercase characters enclosed in single quotes ('...'). 
The single quotes indicate that the uppercase letters are to be 
treated as lowercase by the system. For example: 


PRINT Uys ‘OHN'! : il) D": 'OE' 
Output: 


John Doe (if device is capable of printing lowercase letters) 
or 
JOHN DOE (if device only prints uppercase letters) 


Note that any uppercase characters within single quotes are also 
converted to lowercase. For example: 


PRINT 'John Doe' 
Output: 


john doe (if device is capable of printing lowercase letters) 
or 
JOHN DOE (if device only prints uppercase letters) 


Any character is valid in a lowercase literal string except the 
Single quote character ('). A single quote literal string can 
contain double quotes, and vice versa. 


Literals can also be written using the HEX function. In this 
form, characters in the string are specified by their hexadecimal 
ASCII codes (sometimes called "hex codes"). Each printing character 
(and each of the nonprinting workstation control characters called 
Field Attribute Characters) can be represented by a corresponding 
ASCII code composed of two hexadecimal digits (0 through 9 and A 
through F; see Appendix F for a list of the ASCII hexadecimal codes). 
In a HEX literal, the ASCII hexadecimal codes are placed in 
parentheses following the word HEX. For example, 


PRINT HEX( 414243) 


prints the string ABC, since 41, 42, and 43 are the hexadecimal codes 
for the first three letters of the alphabet. This statement is 
equivalent to PRINT "ABC". HEX(4120422043) corresponds to the same 
sequence of letters, with spaces (ASCII code 20) between them. Any 
legal hexadecimal code may be specified in a HEX literal string. 
The user should, however, be aware of the special use of hexadecimal 
codes 80 through FF (see Subsection 7.3.4). 


Literal strings can also be assigned as values to alphanumeric 
variables. Assignment and other alphanumeric operations = are 
discussed in Section 5.2. . 


3.4.2 Alphanumeric Variables 


Alphanumeric character strings can be stored and processed in an 
alphanumeric string variable (or simply "alpha variable"). Values 
stored in alpha variables can be stored and processed singly, as 
scalar variables, or in groups, as array variables. Alphanumeric 
and numeric arrays are discussed in Section 3.5. The following 
discussion applies to alphanumeric scalar variables. 


Alpha variable names, like those of numeric variables, are 
sequences of up to 64 letters, digits, and underscores, provided 
that the first character of the name is a letter and that the name 
is not a VS BASIC reserved word (see Appendix A). Alpha variable 
names are distinguished from numeric variable names by a dollar sign 
($) appended to the end of the variable name. For example, the 
variable name THING refers to a floating point numeric variable, 
whereas THINGS refers to an alphanumeric variable. Similarly, ITEM% 
is an integer variable; ITEM$ is an alpha variable. A numeric 
variable and an alpha variable are separate and independent 
entities, even if they have the same name exclusive of the "$". 


An alphanumeric variable identifies a unique location in memory 
reserved for the storage of alphanumeric data. The compiler 
reserves space for each variable during compilation, at which time 
the program is scanned for all variable references. The number of 
characters that can be stored in an alpha variable depends on how 
much space is reserved for that variable during compilation. Each 
character requires one byte (eight bits, or binary digits) of 
storage. The amount of space reserved for each variable can be 
specified by the programmer in a DIM or COM statement. For example, 


DIM WORD$ 10, LINE$ 80 
COM HORSE$ 10, COWS 17 


reserves 10 bytes of storage for WORD$, 80 bytes for LINE$, 10 bytes 
for HORSE$, and 17 for COWS, the latter two in the common storage 
area. (For an explanation of common storage, see 
Subsection 6.5.4.) An alpha scalar variable can be specified as 
having any length between 1 and 256 characters (bytes). An alpha 
variable cannot appear more than once in DIM or COM statements in a 
program. If the programmer does not explicitly dimension an alpha 
variable in a DIM or COM statement, the compiler automatically 
reserves 16 bytes for the variable. The DIM and COM statements are 
both also used for dimensioning arrays (see Subsection 3.5.2); the 
COM statement is also used for placing variables of any type in 
common storage (see Subsection 6.5.4 and the COM statement entry in 
Part II). 


NOTE 


Any alpha variable that has not had some other value 


assigned to it is defined as being filled with blanks 
(ASCII code HEX(20)). 


The length of an alpha variable or alpha array element specified 
in a DIM or COM statement is called its "defined" length. In many 
cases, however, the character string stored in an alpha variable 
does not occupy the entire defined length. The last character of an 
alpha variable is normally taken to be the final nonblank character 
(except when the value is all blanks, in which case the value is 
treated as one blank). Hence, trailing blanks generally are not 
considered part of the value of an alpha variable. For example: 


100 A$="ABC" 
200 PRINT A$;"DEF" 


Output: 


ABCDEF (Note that the trailing blanks of A$ were not 
printed. ) 


The character string stored in an alpha variable is called the 
"current value" of the alpha variable, and its length, up to the 
first trailing blank, is called the "current length" (or "actual 
length") of the variable. The length function, LEN, determines the 
current length of an alpha variable. For example: 


100 A$="ABCD " 
200 PRINT LEN(A$) 


Output: 


4 (LEN does not consider trailing blanks to be part of the 
value of an alpha-variable.) 


Most alphanumeric operators and functions operate on the current 
value of an alpha variable. In some cases (e.g., ACCEPT and DISPLAY 
statements), however, the entire defined length of the variable may 
be used. It is therefore important to understand the distinction 
between defined length and current length. 


NOTE 


If the defined length of an alpha variable is greater 
than necessary for storing the value of a given alpha 


expression, the variable is padded with blanks (ASCII 
code HEX(20)) when the value is assigned. 


3.5 ARRAY VARIABLES 


An “array variable" is a collection of scalar variables 
identified by a common name. Each scalar variable contained in the 
array is called an “element" of the array, and can be identified by 
specifying the array name followed by a subscript or pair of 
subscripts, which locate the element within the array. Arrays, like 
scalar variables, can hold floating point, integer, or alphanumeric 
data. A single array cannot hold values of more than one type. The 
names of array variables are formed in the same way as the names of 
scalar variables (a sequence of 1 to 64 letters, digits, and 
underscores, as described in Subsection 3.3.3; names of integer 
arrays must end in % and those of alpha arrays must end in $). The 
one additional restriction on array names is that they cannot begin 
with the characters FN. 


NOTE 


Any attempt to use a name beginning with FN for an array 
will result either in an error message at compilation 
time or in a logically incorrect object program. Any 


name beginning with FN and containing parentheses is 
interpreted by the compiler to refer to a user-defined 
function (see Subsection 4.4.2). 


In general, any reference to an array variable must consist of 
the array name followed by parentheses. If the parentheses enclose 
an expression or a pair of expressions, the expressions are 
interpreted as the subscripts of a particular element in the array. 
For example, the fifth element in floating-point array N() could be 
specified as N(5); BOX$(K) refers to the K-th element of the alpha 
array BOX$(). Note that the subscript is enclosed in parentheses 
immediately following the array name. In situations in which the 
entire array (rather than a particular element of the array) is to 
be referenced, the array name must be followed by empty parentheses 
(e.g., N() or BOX$()) to form an “array-designator." The array name 
alone (e.g., N or BOX$) is used only in special matrix statements 
(e.g., MAT INPUT and MAT PRINT). 


Since scalar variables are different from array variables, the 
same name (i.e., the same sequence of letters, digits, and 
underscores) can be used both as a scalar variable name and as an 
array variable name. Thus N() designates an array variable, while N 
names a scalar variable, except in a matrix statement. In any 
statement except a matrix statement (see Section 9.2), the array must 
always be referenced with an array-designator to indicate an array 
rather than a scalar variable. For example: 


WHALE -—- identifies a floating-point scalar variable. 


WHALE% -- identifies an integer scalar variable. 
WHALE() -- identifies a floating-point array. 
WHALE%() -- identifies an integer array. 

WHALE$ -- identifies an alphanumeric scalar variable. 
WHALE$() -- identifies an alphanumeric array. 


To minimize the chance of confusion, however, use of the same 
name for scalar and array variables in a program is not recommended. 


3.5.1 One-Dimensional and Two-Dimensional Arrays 


Array variables can be either one-dimensional or two-dimensional. 
A one-dimensional array is a list of all variables identified by the 
same name. A two-dimensional array is a table of variables all 
identified by the same name. 


A one-dimensional array can be thought of as a list or column of 
variables (elements), each occupying its own slot, or row, in the 
column. Consider, for example, the representation of array DWARF() 
in Figure 3-1. 


DWARF ( ) 


DWARF (1) 


DWARF (2) 


DWARF (3) 


DWARF (4) 


DWARF'(5 ) 


Figure 3-1. The One-Dimensional Array DWARF() 


X 


Note that DWARF() contains a total of five elements and that 
each element is identified by specifying its row. For example, 
element DWARF(3) is located in Row 3. 


One-dimensional arrays are also called "lists," "vectors," 
"column vectors," and, since each element is identified by a single 
subscript, "singly-subscripted arrays." 


The scheme in Figure 3-1 can be generalized to contain two or 
more columns. When this is done, the result is a two-dimensional 
array. A two-dimensional array can be thought of as a table 
consisting of two or more columns of elements. Consider, for 
example, the representation of the two-dimensional array HOBBIT() in 
Figure 3-2. 
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Column 1 
HOBBIT(1,1) 
HOBBIT(2,1) 
HOBBIT(3,1) 
HOBBIT (4,1) 


HOBBIT (5,1) 


HOBBIT { ) 


Column 2 
HOBBIT(1,2) 
HOBBIT (2,2) 
HOBBIT (3,2) 


HOBBIT (4,2) 


HOBBIT(5,2) 


Column 3 
HOBBIT (1,3) 
HOBBIT(2,3) 
HOBBIT (3,3) 
HOBBIT (4,3) 


HOBBIT(5,3) 


Figure 3-2. The Two-Dimensional Array HOBBIT() 


Note that HOBBIT() consists of three columns of elements, with 
five rows in each column, for a total of 15 elements. In this case, 
it is not sufficient to identify each element by its row, since the 
element may be in Column 1, Column 2, or Column 3. A second 
subscript is required to identify the column. The convention 
followed when referencing a particular element in a two-dimensional 
array is always to specify the row first, and then the column. Thus 
HOBBIT(3,2) identifies the element in Row 3 and Column 2. 


Two-dimensional arrays are also called "tables" or "matrices," 
and, because each element is identified by a pair of subscripts, 
"doubly-subscripted arrays." 


Elements in an array can be referred to by subscripts that are 
legal BASIC expressions. Thus JIM(N) refers to the N-th element of 
array JIM() for whatever value N has at the time of execution. This 
ability to reference an array by a variable subscript is one of the 
useful features of arrays, since it can eliminate a considerable 
amount of repetitive coding. 


For example, the following three statements 
100 FOR I = 1 TO 50 
200 PRINT JIM(T) 
300 NEXT I 
cause the first 50 elements of array JIM() to be printed with 


considerably less coding than 50 consecutive PRINT statements. 


NOTE 


If the value of an expression used as a subscript is not 


an integer at run time, the value of the expression is 
truncated and the integer value is used as the subscript. 
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3.5.2 Dimensioning an Array 


When a program is compiled, the BASIC compiler reserves storage 
space for each variable. To do this, the compiler must know how much 
space to allocate for each variable. Since arrays can be either one- 
or two-dimensional and can contain varying amounts of data, the 
programmer must tell the compiler how much space to reserve for each 
array in a program; that is, the array must be dimensioned. An array 
is dimensioned by specifying whether it has one or two dimensions and 
how many rows (and columns, if two-dimensional) are in the array. 
Dimension information is specified using either the DIM (dimension) 
or COM (common) statement. For example, to allocate space for a 
one-dimensional integer array of 10 elements named VEGETABLE%(), one 
would write 


DIM VEGETABLE% (10) 


If VEGETABLE%() is to be used by more than one program or subprogram 
running together, one would use COM instead of DIM. 


DIM and COM statements can be used to define any number of 
arrays of any type, as long as each array is separated from the one 
following it by a comma. When using DIM or COM to dimension an 
alpha array, the length of each element in the array can be 
specified as an integer immediately following the right parenthesis. 
For example, 


DIM NAME$(500)10, CITY(100), STATE(5,10) 
COM CODE$(20,10)5, ZIP%(1000), COUNT% 


defines a 500-element one-dimensional alphanumeric array (NAME$()) 
where each element is 10 bytes long, a 100-element one-dimensional 
floating-point array (CITY()), a 5-row by 10-column two-dimensional 
floating point array (STATE()), a 20-row by 10-—column 
two-dimensional alpha array (CODE$()) with each element 5 bytes 
long, and a 1000-element one-dimensional integer array (ZIP%). The 
latter two arrays are designated as common, as is the integer scalar 
COUNT%. The use of DIM and COM statements to specify the length of 
alpha scalars is discussed in Subsection 3.4.2. 


If an array is not dimensioned before its first occurrence in an 
executable program statement, the compiler automatically assigns 
default dimensions of 10 rows by 10 columns. In the case of alpha 
arrays, each element is assigned a default length of 16 bytes. 
Therefore, any array which is to be of any other dimension must be 
dimensioned before its first occurrence in an executable statement. 
No array can be dimensioned more than once in a program. Row and 
column dimensions specified: in DIM or COM statements must be between 
1 and 32,767. 
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The total size of all the variables in a program, including array 
variables, cannot exceed the available Segment 2 address space. The 
Segment 2 address space is limited to a maximum of 512K (524,288) 
bytes on all VS systems. If the variables in a source program 
require more than 512K bytes of storage, the compiler issues an error 
message and halts code generation. 


Although programs can be compiled with up to 512K bytes of 
variable storage space (Segment 2 space), the resulting object 
program cannot be executed unless there is sufficient space available 
on the particular VS configuration at run time. In addition, each 
User ID has an associated maximum Segment 2 size that can be less 
than or equal to the system maximum; a program will not run unless 
the user's Segment 2 size is sufficiently large. 


Thus, the fact that a particular program compiled successfully on 
a particular system does not guarantee that it will also run on that 
system. For example, on a VS system with only 256K bytes of Segment 
2 space allocated to each task, a program requiring 400K of Segment 2 
space would compile with no errors (assuming it were syntactically 
correct), but would not run due to insufficient memory to store the 
variables during execution. Likewise, a user with a Segment 2 size 
of 256K bytes on a system with a maximum of 512K bytes could compile 
a program requiring 400K bytes of variable storage, but the compiled 
program would not run. 


Since DIM statements are processed during compilation, prior to 
program execution, they cannot be supplied with variable subscripts, 
Since the value of the variable is unknown at that time. The 
following statement, for example, produces an error message: 


DIM A1(5,N) 
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CHAPTER 4 
NUMERIC OPERATIONS 


4.1 INTRODUCTION 


Numeric data (see Section 3.3) is manipulated in VS BASIC by 
means of operators and functions. An operator is a symbol (such as 
+ or -) that specifies some operation (such as addition or 
subtraction) to be performed, usually involving two numeric 
quantities. A function is a construct that performs some series of 
operations on one or more input values (called arguments) and 
returns a single output value. For example, SIN(X) and SQR(X) are 
functions that calculate the sine and square root of an argument, in 
this case of the variable X. A number of numeric’ constants, 
variables, and functions connected by numeric operators constitutes 
a numeric expression. When values are supplied for any variables in 
an expression, the value of the expression is determined by 
performing the indicated operations and functions. This occurs when 
a statement containing an expression is executed when a program is 
run. The value of the expression is then used in whatever way is 
indicated by the particular statement being processed. 


4.2 NUMERIC OPERATORS 


There are three types of numeric operators used in BASIC: 
assignment, arithmetic, and relational. The assignment operator 
assigns a value to a particular variable. The arithmetic operators 
specify the basic arithmetic operations that can be performed on 
numeric quantities: addition, subtraction, multiplication, 
division, exponentiation, and negation. Relational operators 
specify comparisons to be made between two numeric values so that a 
program may take different actions depending on whether one value is 
greater than, equal to, or less than another. 


4.2.1 The Assignment Operator 


The equals sign (=) is the assignment operator used only in 
assignment statements. An assignment statement stores the value of 
the expression on the right of the equals sign in the variable(s) 
named to the left of the equals sign. An assignment statement 
consists of the optional reserved word LET, followed by one or more 
variable names, followed by the equals sign, followed by a numeric 
expression. For example: 


LET SUM=A+B 
LET SQUARE(5,17)=(ZONK-POW) +10 
LET SLITHEY_TOVES, MOME RATHS = VORPAL/FRUMIOUS 


The keyword LET can be omitted: 


Note that the equals sign has a different meaning in contexts other 


DIFFERENCE=A-B 
CABBAGES, KINGS=10 


than assignment statements (see Subsection 4.2.3). 


4.2.2 Arithmetic Operators 


The following symbols are used as arithmetic operators: 


Symbol Operation Sample Expression Explanation 

f or ** exponentiation ATB or A**B Raise A to the power B. 
* multiplication A*B Multiply A by B. 

/ division A/B Divide A by B. 

+ addition A+B Add B to A. 

- subtraction A-B Subtract B from A. 

= unary negation —-—A Negate A. 


NOTE 


All arithmetic operations must be explicitly specified. 
In normal algebraic notation, expressions such as AB or 


A(B) can be used to indicate multiplication; in BASIC, 
the operation must be explicitly specified (e.g., A*B.) 


When a numeric expression is evaluated, arithmetic operations 


are performed in the following order or hierarchy: 


1. All operations within parentheses are performed. 
innermost parenthesized expressions are evaluated first. 


2. All unary negation (-) and exponentiation (fT or 
operations are performed (left to right). 


3. All multiplication (*) and division (/) operations 
performed (left to right). 


4. All addition (+) and_ subtraction (-) operations 
performed (left to right). 


NOTE 


Every arithmetic operator must be followed by a numeric 
expression. Thus it is not permissible to have an 
operator immediately followed by another operator, as in 


A-*B. To indicate an operation on the negative of an 
expression, parentheses must be used to enclose the 
expression and the negating minus sign. For example, 
A*(-B) is permissible, but A*-B is not. 


When there are no parentheses in the expression and the operators 
are at the same level in the hierarchy, the expression is evaluated 
from left to right. Parentheses can be used to group operations and 
so alter the order of evaluation of terms within an expression. 
Quantities within parentheses are evaluated before the parenthesized 
quantity is used in further computations. For example: 


A*B/C A is multiplied by B; the product is then divided by 
Ce. 

A* (B/C) B is divided by C; the quotient is then multiplied 
by A. 

X+Y*Z Y ais multiplied by 2Z (multiplication precedes 
addition by Rule 3 above); the product is then added 
to X. 

(X+Y) *Z Y is added to X; the sum is then multiplied by Z. 

Parentheses can be "nested" to any level. That is, a 


parenthesized expression can contain other parenthesized expressions, 
as in A+(B-((C/D)**2)). In such cases, the expression within the 
innermost set of parentheses is evaluated first, and evaluation 
proceeds to the outermost set of parentheses. For every left 
parenthesis there must be one matching right parenthesis at some 
later point in the expression. 


When in doubt, parentheses can always be used to insure that a 
complex expression is evaluated in the intended way. Redundant 
parentheses have no effect on the order of evaluation of an 
expression. 


4.2.3 Relational Operators 


Relational operators are used in IF...THEN statements when 
values are to be compared. 


For example, when the statement 

IF G<10 THEN 60 
is executed, if the value of G is less than 10, processing continues 
at program line number 60. Otherwise, execution continues in the 


normal sequence with the statement following the IF statement. 


The following relational symbols are used in VS BASIC: 


Symbol Sample Relation Explanation 


= A=B A is equal to B. 

< A<B A is less than B. 
<= A <= B A is less than or equal to B. 

> A>B A is greater than B. 

>= A >= B A is greater than or equal to B. 
<> A <> B A is not equal to B. 


These symbols are also used in the POS function and the SEARCH 
statement (see Section 5.6 and the SEARCH statement entry in Part 
II). 


4.3 NUMERIC EXPRESSIONS 


A numeric expression is either one or a series of constants, 
variables, or functions, connected by arithmetic operators. Numeric 
expressions can be evaluated in a variety of different BASIC 
statements. In the following examples, valid numeric expressions 
are boxed: 


INDEX = 
PRINT 
TO 4*Y STEP 


Most commonly, expressions are evaluated and their values assigned 
to variables in assignment (LET) statements (see Subsection 4.2.1), 
or they are evaluated and their values printed or displayed in PRINT 
statements. Operations in an expression are performed in sequence 
from highest priority level to lowest (see Subsection 4.2.2). 


PHONE 


FOR I 


4.4 NUMERIC FUNCTIONS 


A numeric function is a construct in the BASIC language that 
takes one or more numeric expressions as input values (called 
arguments), performs some series of operations on them, and returns a 
Single numeric output value. The value of the function can be used 
anywhere a numeric expression is allowed, such as on the right-hand 
side of an assignment statement or as part of a larger numeric 
expression. 


Syntactically, a function is written as follows: 
fname[ (argument[,argument][,...])] 


where "fname" is the name of a function, and "argument" is any 
expression acceptable to the particular function used. Expressions 
used as the arguments of a function are evaluated before the 
computation indicated by the function is performed. The result of 
this computation can be used as part of a larger expression. For 
example, 


100 LET X=SIN(Y/2)+1 


causes: (1) the expression Y/2 to be calculated, (2) the sine of 
that expression to be determined (SIN is the function name), (3) 1 
to be added to the sine, and (4) the assignment of the final value 
to the variable X. 


VS BASIC recognizes two major kinds of numeric functions: 
intrinsic and user-defined functions. 


4.4.1 Intrinsic Functions 


Intrinsic (or "built-in") functions are defined within the BASIC 
language and can be used at any time in a program. The twenty-five 
intrinsic functions recognized by VS BASIC include all mathematical 
functions such as trigonometric, absolute value, and logarithmic 
functions. A random number’ generator and various functions 
specialized for use in data processing are also available. The 
intrinsic numeric functions vary in the type and number of arguments 
that they require, but all return numeric values. 


In addition to the intrinsic functions, VS BASIC also has an 
intrinsic named constant, which is PI. PI may be used anywhere a 
numeric expression is allowed, and has the value 3.14159265358979. 


The intrinsic numeric functions are discussed below and in Part 
II of this manual. 


The SIZE function, which deals with file I/0, is discussed in 
Section 8.5. 


Trigonometric Functions 


The sine, cosine, tangent, arcsine, arccosine, and arctangent 
functions are available in BASIC. Other trigonometric functions can 
be easily expressed using combinations of these functions. Each of 
these functions takes one numeric argument, and returns a floating 
point value. 


Function Meaning 

SIN(x) The sine of x. 

COS(x) The cosine of x. 

TAN (x) The tangent of x. 

ARCSIN(x) The inverse sine (Arcsine) of x. 

ARCCOS (x) The inverse cosine (Arccosine) of x. 

ARCTAN (x) The inverse tangent (Arctangent) of x. 

ATN (x) Same as ARCTAN (ATN is a synonym for ARCTAN). 


These functions can express and accept angular measure in 
degrees, radians, or grads (400 grads = 360 degrees). Radian measure 
is used as the default in every program or subroutine, until one of 
the following statements is encountered: 


SELECT DEGREES -- which selects degrees. 
SELECT GRADS -- which selects grads. 
SELECT RADIANS -- which selects radians. 


The mode used at any time is determined by the most recently 
executed SELECT statement in that program or _ subroutine. For 
instance, a program can execute a SELECT DEGREE statement, thus 
changing the trig mode to degrees. If it then uses the CALL 
statement to call a subroutine, the mode becomes radians, assuming 
the subroutine has not previously reset the mode. If the subroutine 
executes a SELECT GRADS’ statement, the mode for subsequent 
trigonometric functions becomes grads. When the END statement is 
executed, returning control to the calling program, the mode reverts 
to degrees. If that subroutine is called again, the initial mode 
will be grads. 


The SELECT statement is discussed further in Part II. The 
arguments of the sine, cosine, and tangent functions are interpreted 
as degrees, grads, or radians depending on the SELECT setting in 
effect at the time of execution. The values returned by the inverse 
trigonometric (arc) functions are likewise in degrees, grads, or 
radians according to the SELECT setting. 


Other Numeric Functions 


The remaining eighteen numeric functions are described below. 
For more detailed descriptions of these functions (including which 
functions return integer values and which return floating-point 
values) see the appropriate entries in Part II. 


DIM(x(),d) 


MAX(x,y,Z,...) 


MIN(x,y,Z, coe ) 


MOD(x,y) 


The absolute value 
of the argument: 
-x if x < 0; x if 
x >= 0. 


The maximum lst or 
2nd subscript of the 
array x. 


The exponential 
function; "e" 
(2.718...) raised 
to the x-th power. 


The greatest integer 
less than or equal 
to x. 


The actual length, 
in bytes, of a$. 


Common (base 10) 
logarithm of x. 


Natural (base "e") 
logarithm of x; 
inverse function 
of EXP. 


The value of the 
largest element in 
the argument list. 


The value of the 
smallest element in 
the argument list. 


The modulus function; 


the remainder of the 
division of x by y. 
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Number and 
type of arguments 


1 numeric. 


1 array designator (x()), 
1 integer (d) = 1 or 2. 


l numeric. A float 
binary argument must range 
from —180.217823392959 to 
174.667963000575. A float 
decimal argument must 
range from 
-180.217823392959 to 
145.062860858624; 0 is 
returned for values less 
than —149.668031044613. 


1 numeric. The input 
value cannot be 
outside the range of 
legal integers. 


1 alphanumeric. 


1 numeric. 


1. numeric. 


1 or more numeric scalars 
or numeric array 
designators. 


l or more numeric scalars 
or numeric array 
designators. 


2 numeric. 


| Number and 
Function Meaning type of arguments 


The number of sequen- | 1 alphanumeric. 
tial ASCII characters 

in a$, starting with 

the first character, 

that represent a legal 

BASIC number. 


POS (a$<b$) The position of the 2 alphanumeric. 
first character of 
a$ that is <, < =, 
a5 Po SER DOL = 
the first character 
of b$. 


RND(x) A pseudo-random number | 1 numeric. 
between zero and one. 


ROUND (x,n) The value of x, 1 numeric (x), 1 
rounded off to n integer (n). 
decimal places. 


SGN(x) The signum function; 1 numeric. 
~l1 if x is negative, 
0 if x is zero, or +1 
if x is positive. 


SIZE(#n) The size in bytes of 1 integer file—expression. 
the most recently read 
record from file #n. 
(See Section 8.5.) 


SOR(x) The square root of x. 1 numeric. 


VAL (a$,d) The numeric value of 1 alphanumeric (a$), 
the first d bytes 1 integer (d) = 1,2,3, 
of a$. or 4. 


The DIM, RND, and ROUND functions are discussed here in more detail. 
DIM 


The DIM function (not to be confused with the DIM statement) 
requires two arguments: the first must be an array-designator (the 
array name plus parentheses, e.g., A()) occurring in the BASIC 
program; the second must be an expression whose value is either 1 or 
2. The DIM function returns either the row or column dimension of 
the named array. 


DIM(X(),1) -—- returns the row dimension of the array X. 
DIM(X(),2) -—- returns the column dimension of the array X. 


RND 

The RND (random number) function is used to produce a 
pseudo-random number between 0 and 1. The term "pseudo-random" is 
used because a digital computer cannot produce truly random numbers. 
Instead, each time the RND function is called, it uses an internally-— 
stored number as a "seed" from which to generate the next "random" 
number by a fixed internal algorithm. Since the algorithm is always 
the same, it always produces the same value for a given seed value. 
By calling the RND function repeatedly and using the output value of 
each call as the seed for the next one, a sequence of numbers is 
generated that, though obviously not truly random, is’ scattered 
about in the range zero to one in such a manner as to appear random; 
thus the term "pseudo-random." 


There are three different ways in which the RND function can be 
used: (1) to generate a pseudo-random number based on a seed value; 
(2) to reset the seed value to some number specified by the user 
program (as either a constant or a variable); (3) to reset the seed 
value based upon the time-of-day clock when the program is run. 
Which mode of operation is selected depends upon the value of the 
expression used as an argument in the function RND(expn) as follows: 


l. expl < 0 or expl >= 1 


If the argument (expl) is less than zero or greater than or 
equal to one, RND produces a pseudo-random number from the 
seed value. If this is the first use of RND in the program, 
the seed has a value set by the BASIC compiler during 
compilation. Otherwise, it has the value produced by the 
last RND call executed. 


2. O< exp2 <1 


If the argument (exp2) is between zero and one, RND returns 
the argument itself as the result and resets the seed to 
this value. The next use of RND, as in Option 1 above, uses 
the value of the previous argument (exp2) as the seed from 
which to generate a pseudo-random value. MThis allows the 
user to produce the same sequence of random numbers any 
number of times within the same program or within different 
programs. 


3. exp3 = 0 


If the argument is equal to zero, RND produces a number 
whose value is computed from the time of day when the RND 
function is executed, rather than from a user or compiler 
specified value. This option can be used to reset the seed 
to a random value, so that on subsequent calls using Option 
1, a more seemingly random series of numbers is produced. 


Note that although Option 3 produces a random number in the 
sense that it generally differs each time this option is’ used, 
repeated RND calls using this option within a program do not produce 
a dependably random list of numbers. (This is because the relation 
between successive numbers in such a list is a function of the time 
elapsed between function calls.) To produce a more random list, use 
Option 3 once, followed by as many Option 1 calls as desired. 
Option 3 should be used only to reset the random number list to a 
new starting value, not to produce such a list. 


Example: 
100 LET A= RND(.5) 
200 LET B= RND(2) 
300 LET C= RND(2) 
400 PRINT "A=";A, "B=";B, "C=";C 
Result: 
A=.5 B=.259780899273209 C=.2989807370711264 


Every time this program is run, it produces the same list of 
numbers. 


ROUND 
ROUND(X,N) is equivalent to the expression: 
SGN(X)*( INT(ABS(X)*1OT(CINT(N))+0.5)/10T(INT(N)) ) 


The ROUND function is used to round off the value of X to the 
precision specified by N. If N is positive, X is rounded off so that 
the last significant digit of the function value is the N-th digit to 
the right of the decimal point. If N is negative, X is rounded off 
so that the last significant digit of the function value is the 
(1-N)th digit to the left of the decimal point. For example: 


ROUND (123.4567,4) = 123.4567 
ROUND (123.4567,3) = 123.4570 
ROUND (123.4567,2) = 123.4600 
ROUND (123.4567,1) = 123.5000 
ROUND (123.4567,0) = 123.0000 


ROUND (123.4567,-1)= 120.0000 
ROUND (123.4567,-2)= 100.0000 
ROUND (123.4567,-3)= 0 
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4.4.2 User-Defined Functions 


User-defined functions enable the programmer to specify any 
sequence of numeric operations to be performed on a single numeric 
argument and to identify that sequence of operations by a function 
name. Functions are defined using the DEF statement. The DEF 
statement has the form 


DEF fname(%](arg) = exp 


where fname is the function name, arg is a "dummy argument," and 
exp is any valid numeric expression. Function names are formed 
according to the same rules that apply for naming scalar variables 
(see Subsection 3.3.3). Although it is permissible to have 
functions with the same names as variables in a program, this is not 
recommended. The dummy argument "arg" is used simply to indicate 
the position in the function definition that is to be taken by the 
argument value when the function is called, and can be any valid 
variable name. For example, 


DEF AREA(X) = 3.14159265 * X**2 


defines a function that determines the area of a circle given the 
radius. In this case, AREA is the function name, and X is a dummy 
argument. The function can be called by a statement elsewhere in 
the same program, such as 


LET SEMICIRC = AREA(RADIUS) /2 
When this statement is executed, the expression in the DEF statement 
is evaluated, with the value of RADIUS substituted for xX. This 


value is returned to the LET statement, and is then divided by 2. 
The resulting value is assigned to the variable SEMICIRC. 


NOTE 


A function can be defined anywhere in a program, but if 
the first use of a function precedes its definition, the 
function name must begin with the characters’ FN. 


Otherwise, the BASIC compiler interprets the function 
call as an array name reference. This results in either 
an error message at compilation time or in logic errors 
in the program. 
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4.5 MIXED MODE ARITHMETIC 


BASIC allows mixed-mode arithmetic, i.e., floating-point or 
integer variables can be assigned either floating-point or integer 
values, with floating-point values truncated to integers. 
Specifically, 


l. Assignment ( [LET] ) statements allow mixed-mode assignment. 


2. Statements performing implicit assignment, such as CONVERT, 
GOSUB'(), INPUT, ACCEPT, READ, and calls to user-defined 
functions allow mixed-mode. The only exceptions to this are 
the CALL and SUB statements, which do not allow mixed mode 
argument passing. 


3. The percent sign (%), used to indicate an integer value, may 
only be used as a numeric symbol when it appears as such in 
the source file; in particular, INPUT, ACCEPT, GET, READ, 
and CONVERT do not allow % as numeric’ input. Thus, 
floating-point constants must be used. 


4. Expressions in integer syntax are also treated like 


mixed-mode assignments (truncated to integer) (e.g., 
BIN(expr), END expr, ON expr GOTO..., RESTORE expr). 


4.6 SUMMARY OF NUMERIC DATA TYPES AND TERMS 


4.6.1 Floating-Point Data 


The allowable range of magnitudes for float binary values is 
from approximately 5.4 x 10°’° to 7.2 x 10’°; the magnitude of 
float decimal values can range from 1 x 10°°° to approximately 
1 x 10°*. Floating-point values with magnitudes outside of the 
operant range cause conditions called underflow (magnitude too 
small) and overflow (magnitude too large). 


The following are classified as floating-point values: 
1. The value of any floating-point variable (no % or $). 
Examples: A, OPHIDIAN, FRUIT(3), D4(X,5) 
2. Any numeric constant with no %. 
Examples: 5, 3.7, -6.321E3, 1E-1 
3. The result of any valid numeric function except LEN, NUM, 
POS, VAL, SGN, SIZE, DIM, ABS(integer), user-defined integer 
functions (the function name ends in %), and under certain 


conditions MIN, MAX, and MOD. 


Examples FN2(2%), SIN(3), ABS(-12) 
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4.6.2 


The result of any binary operation (+, -, *, /, T, **) 
or MOD function whose two arguments are not both integers. 


Examples: 2/5, 3%T17, 4%+SQR(16) 


The result of the MAX and MIN functions when the arguments 
are not all integers. 


NOTE 


If the evaluation of any numeric expression during 


program execution results in a float binary value with a 
Magnitude greater than approximately 7.2 x 10’° or a 
float decimal value greater than 1 x 10°° (i.e., an 
overflow condition), an error occurs, program execution 
halts, and an appropriate error message is displayed on 


the workstation. Evaluation of float binary expressions 


with. magnitudes less than 5.4 x 10°’° (underflow) or 


float decimal expressions with magnitudes less than 
1x 10°°* are treated as zero and do not cause an 
error. A numeric constant that is either too large or 
too small causes an error during compilation. 


Integer Data 


The allowable range of values for integer values is from 
—2,147,483,648 to 2,147,483,647. 


The following are classified as integer values. 


Es 


The value of any integer variable (variable name ending with 
AL | , 


Examples: A%, OPHIDIAN%, FRUIT%(3), D4%(X,5) 


Any integer constant, which must contain a trailing "%," no 
decimal point, and no exponent. 


Examples: 375%, -10000%, 2% 
The result of the numeric functions LEN, NUM, POS, VAL, SGN, 
SIZE, DIM, ABS (integer), and user-defined integer functions 
(function names ending in "%"). 


Examples: FN3%(7.5), SGN(THE TIMES), SIZE(#5) 


Fhe result of any binary operation (+, -, *, /, T, **) or 
MOD function whose two arguments are both integers. 


Examples: 2%/5%, 3%T(17%), 4% + LEN(B$) 
The result of the MAX and MIN functions when the arguments 


are all integers. 
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NOTE 


If the evaluation of any numeric expression during 
program execution results in an integer value outside 
the allowable range (-2,147,483,648 to 2,147,483,647), 


an error occurs, program execution halts, and an 
appropriate message is displayed on the workstation. 


4.6.3 Numeric Terms 


1. Constant: + floating-point constant 
- integer constant 


2. Expression’: numeric variable 
(or exp) constant 


mathematical function 
DIM function 
LEN function 
NUM function 
POS function 
SIZE function 
user-DEFined function 
VAL function 


+ 
+ expressionk< * Sexpression 
- / 
Hs 
kk 
(expression) 
3. Integer (or int): digit [digit]...% 
letter 
4. Numeric Array-designator: letter digit 
underscore 


(not to exceed 64 letters, digits, and/or underscores) 


letter 
5. Numeric Array Name: letter digit 
underscore 


(not to exceed 64 letters, digits, and/or underscores) 


we - a Aw as Mc ee os ae a RE 
Adjacent operators are not allowed (e.g., A++B). 
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letter 


Numeric Array Variable: letter digit ise 1 
[exp] 
underscore 


(not to exceed 64 letters, digits, and/or underscores) 


letter 
Numeric Scalar Variable: letter digit eee: 11%] 
underscore 


(not to exceed 64 letters, digits, and/or underscores) 


Numeric Variable: numeric scalar variable 
numeric array variable 


Mathematical Function: PI, ABS, ARCCOS, ARCSIN, ARCTAN, 
ATN, COS,EXP, INT, LGT, LOG, MAX, MIN, MOD, RND, ROUND, SGN, 
SIN, SQR, TAN functions. 
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CHAPTER 5 
ALPHANUMERIC OPERATIONS 


5.1 INTRODUCTION 


Alphanumeric data (or simply "alpha data") is manipulated in VS 
BASIC by alphanumeric operators and functions. Alpha operators and 
functions are different from their numeric counterparts described in 
the previous chapter, even though in some cases (such as assignment 
statements) the same symbol may be used as either a numeric or an 
alphanumeric operator. In these cases, the meaning of the symbol is 
inferred from the data type of the two operands involved. Functions 
that return alpha values are called alpha functions. In addition, 
there are some numeric functions that take alpha arguments. Both 
are discussed below. A series of literals, alpha variables, or 
alpha functions connected by alpha operators constitutes an alpha 


expression. 


In addition to facilities for manipulating characters and 
strings of characters, VS BASIC also provides logical functions that 
enable the programmer to specify operations on individual bits 
within a stored character. It is also possible to convert 
alphanumeric representations of numbers to numeric form and vice 
versa using the CONVERT statement, which is discussed in Part II of 
this manual. 


5.2 ALPHANUMERIC OPERATORS 


The alphanumeric operators in VS BASIC are the assignment 
operator, the concatenation operator, and relational operators. 


5.2.1 The Assignment Operator 


The equals sign (=) is used as the alphanumeric assignment 
operator in a LET statement, just as it is for numeric assignment. 
An alphanumeric assignment statement consists of the reserved word 
LET (optional), followed by one or more alphanumeric variable names 
or other alpha receivers (see Subsection 5.4.2) followed by the 
equals sign, followed by an alpha expression. 


When the statement is executed, the value of the alpha expression 
is stored into the variable(s) or receiver(s) one character at a 
time, left to right. This continues until all the characters of the 
evaluated expression are used up or until the alpha variable or 
receiver is full. Thus, if the defined length of the alpha receiver 
is less than the length of the evaluated expression, the rightmost 
characters of the value of the expression are lost. If the defined 
length of the alpha variable or receiver is greater than the length 
of the value of the alpha expression, the remaining bytes of the 
alpha expression are filled with trailing blanks. For example: 


100 DIM A$50, B$5, C$10, D$10 

200 A$="THE TIME HAS COME, THE WALRUS SAID" 
300 BS=A$ , 

400 C$=BS 

500 DS=A$ 

600 PRINT A$ : PRINT BS : PRINT C$ : PRINT D$ 


Output: 


THE TIME HAS COME, THE WALRUS SAID 
THE T 

THE T 

THE TIME H 


5.2.2 The Concatenation Operator 


The concatenation operator (&) combines two strings, one 
directly after the other, without intervening characters. The two 
strings combined by the concatenation operator are treated as a 
Single string. For example: 


100 A$="WASTE" 
200 BS="LAND." 
300 C$=A$ & BS 
400 PRINT C$ 


Output: 
WASTELAND. 


Literal strings expressed as constants can be concatenated with 
literal strings stored as the values of alpha variables. For 
example: 


100 A$="BY" 

200 B$S="T.S. ELIOT" 
300 C$=AS & " " & BS 
400 PRINT C$ 


Output: 


BY T.S. ELIOT 


Any legal alpha expression, including HEX literal strings, can 
be concatenated with alpha literals or alpha variables. For example: 


100 A$ = "APRIL IS THE CRUELEST MONTH" 


200 C$ = A$ & HEX(2C) & " BREEDING" /* HEX(2C)="," */ 
300 PRINT C$ 
Output: 


APRIL IS THE CRUELEST MONTH, BREEDING 


5.2.3 Relational Operators 


Relational operators are used in IF...THEN statements and in the 
POS function (see Section 5.6) to compare values of alphanumeric 
data. 


In IF...THEN statements, the values of two strings are compared 
one character at a time on the basis of their position in the ASCII 
collating sequence (see Appendix G). In such a comparison, the 
first characters of each string are compared. If they are 
different, the string containing the character of a higher position 
in the collating sequence is the greater of the two. If they are 
the same, the second characters of the two strings are compared in 
the same way; this process is repeated until a pair of unequal 
characters is found or until one or both strings is exhausted. If 
the strings are of unequal length, the shorter one is treated as 
though: it had enough trailing blanks to make it the same length as 
the longer one, and the comparison continues one character at a 
time. This usually places the shorter string earlier in _ the 
collating sequence, since few characters have a lower ASCII value 
than the space (HEX(20)). If the strings are of equal length and 
the comparison shows all characters to be the same, the strings are 
equal. 


The relational operators used with alphanumeric data are the 


same as those used for numeric relations. They have the following 
meanings when used with alphanumeric data: 


Ss ol Sample Relation Explanation 


= AS = BS A$ is at the same position as B$ 
in the collating sequence. 

< AS < BS A$ precedes B$ in the collating 
sequence. 

<= A$ <= B$ A$ precedes or is at the same 
position as B$ in the collating 
sequence. 

> AS > BS A$ follows BS in the collating 
sequence. 
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Symbol Sample Relation Explanation 


>= A$ >= BF A$ follows or is at the same 
position as B$ in the collating 
sequence. 

<> A$ <> BS A$ is at a different position 


from B$ in the collating sequence. 


5.3 ALPHA ARRAY STRINGS 


An entire alpha array can be treated as a single alpha variable 
wherever an alpha variable would be allowed. In this case, the alpha 
array is referred to by its name followed by "()" (the same form used 
for array-designators). The array is treated as a single continuous 
character string, called an alpha array string, which in memory is 
equivalent to a row-by-row path through the elements of the array. 
For example: 


100 DIM A$(2,2)3 
200 A$(1,1)="1":A$(1,2)="2" :A$(2,1)="3":A$(2,2)="4" 
300 PRINT A$() 


Output: 
1 2.3 4 


Although alpha array strings and alpha array-designators look 
alike, their usage is generally determined by the syntax. There are 
cases, however, in which both scalars and arrays are allowed. In 
these cases, an argument such as A$() is always regarded as an 
array-—designator, never as an array string. The statements in which 
this can occur are: 


ACCEPT CALL GET DISPLAY SUB PUT Disk I/O Statements 


In these cases, STR can be used (e.g., STR (A$())) to indicate 
that the variable is to be treated as an array string and not as an 
array designator. 


5.4 ALPHA EXPRESSIONS AND ALPHA RECEIVERS 


5.4.1 Alpha Expressions 


An alpha expression is either one or a series of literals, alpha 
variables, alpha array strings, or alpha functions connected by 
concatenation operators (&). Alpha expressions can be evaluated in 
a variety of VS BASIC statements. In the following example, valid 
alpha expressions are boxed: 


as =[ BS | 

IDENT$ = | NAME$ & "/" & ADDRESS$ & "/" & SOCSECS | 
PRINT | TEMP$(I) |; 

IF [ STR(PHRASE$(T)) ] >= THEN 


REARRANGE 


FOR K=1 TO LEN( | CUCUMBER$() | ) 


5.4.2 Alpha Receivers 


An alpha-receiver is an alphanumeric item into which data can be 
stored, such as a variable or an array. Alpha-receivers are used 
wherever a value is "received," e.g., on the left side of a LET 
statement, in the argument list of a READ statement, etc. 


The following are the only legal alpha-receivers in BASIC: 
alpha variable (e.g., A$, A$(1,2)) 
alpha array string (e.g., B$()) 


STR function* (e.g., STR(A$,1,1)} 
KEY function (see Section 8.5) 


* Only when the first argument is an alpha-receiver. 
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5.5 ALPHANUMERIC FUNCTIONS 


Eight BASIC functions return alphanumeric values. 


Number and type 
Function Meaning of arguments 


ALL (a$) A character string 1 alphanumeric, 
consisting entirely of 
characters equal to 
the first character of 


af. 


BIN(x,d) An alphanumeric 1 numeric (x), 
string of d characters 1 integer (d) 
whose decimal ASCII 3, or 4. 
value is the integer 
part of x. 


A six-character string 
giving the current 
date in the form YYMMDD. 


FS (#n) A two-character code 1 file expression. 
indicating the file 
status for the most 
recent I/O operation 
involving file #n. 
(See Section 8.5.) 


The value of the "key" 1 file expression. 
field for the last 

record read from file 

#n. (See Section 8.5.) 


MASK (#n) The value of the two- 1 file expression. 
character alternate key 
mask for the last record 
read from file #n. 
(See Section 8.5.) 


STR(a$,n,m) | The substring of a$ 1 alphanumeric (a$), 
that begins at the 2 numeric (n,m). 
n-th character of a$ 
and is m characters long. 


An eight-character 
string giving time of 
day to the hundredth of 
a second in the form 
HHMMSShh . 


Further discussion of these functions can be found under their 
respective entries in Part II. 


NOTE 


The STR function can be used to refer to the entire 
defined length of an alpha variable, including trailing 
blanks, by omitting the second two arguments. See Part 
II for examples of this use. 


5.6 NUMERIC FUNCTIONS WITH ALPHA ARGUMENTS 


VS BASIC supports four functions that take alpha expressions as 
arguments and return integer values. These are summarized in the 
following table, and described in more detail below. 


LEN The current length of 
the argument. 


The number of consecutive 
characters in the 
argument, starting at the 
first, that form an ASCII 
representation of a valid 
BASIC number. 


POS (X$="$") The position within the 
first argument of the 
first character that 
satisfies the indicated 
relation (equal to, less 
than, greater than) with 


the second argument. 


VAL (X$,N) The decimal equivalent of 


the binary numeric value 
of the first N characters 


of X$. 


5.6.1 LEN 
The LEN function requires an alpha-expression as its argument, 
and returns an integer value that is the actual length of the 
argument. The length of a string of all blanks is 1. For example: 
LEN("ABCDE'') -- Returns 5. 
LEN(E$) -- Returns the actual length of E$. 
LEN(STR(E$)) -- Returns the defined length of E$. 
Note that the relation 
LEN (A$&B$ ) =LEN (A$) +LEN (BS) 


is always true. 
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5.6.2 NUM 


The NUM function requires an alpha expression as an argument, and 
returns an integer value equal to the number of sequential characters 
in the argument that form a legal BASIC floating-point constant. 
Allowable characters are 0 through 9, E, ., +, -, and space (in the 
leading or trailing position), provided that they conform to the 
syntax for floating-point constants. 


The count begins with the first character of the argument, and 
ends with the first character that violates the floating-point 
syntax. NUM searches the entire defined length of the argument; if 
no characters are found that violate the floating-point syntax, NUM 
returns the defined length. If the argument is entirely blank, NUM 
returns 0. Leading and trailing spaces are included in the count. 
Thus: 


NUM ("l1E 88") returns 1. 
NUM ("1E8 8") returns 4. 
NUM (" 1E8 8") returns 5. 


NUM can be used to validate an alphanumeric representation of a 
number before attempting to convert it to internal numeric binary 
form with the CONVERT statement, described in Part II. 


NUM does not stop its search after finding more than fifteen 
digits in the numeric constant, even though subsequent attempts to 
evaluate that number ignore all digits other than those belonging to 
an exponent after the fifteenth significant digit. 


Note that NUM does not check the value of a number, only whether 
it is formatted correctly. Thus NUM("1E88") returns 4, even though 
1E88 is greater than the largest allowed floating-point constant. 


5.6.3 POS 


The POS function requires three components in its argument (not 
to be separated by commas): (1) an alpha expression, optionally 
preceded by a minus sign; (2) a relational operator; and (3) a second 
alpha expression. The relational operator is taken from the set: 


< 
<= 
> 
>= 
<> 


The POS function searches the first string for a character that 
satisfies the specified relation to the first character of the second 
string. Thus, POS (E$<="*") searches E$ for a character less than or 
equal to "*", 
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Comparisons are based on the ASCII-coded values of the 
characters. Thus, searching a string for a character less than or 
equal to " " means searching a string for a character whose 
hexadecimal value is less than or equal to HEX (20), the ASCII value 
of the space character. 


The POS function returns an integer value that is the position in 
the first expression where the comparison first succeeds. The 
leftmost position in the expression is named 1; the position to the 
right of that is 2, and so on. If no character is found within the 
first expression that satisfies the relation, POS returns a value of 
0. 


The optional minus sign to the left of the first alpha expression 
indicates the direction of the search. Normally, searches are left 
to right; if the minus sign is present, the search proceeds from 
right to left. The entire defined length of the expression is 
searched until either a match is found or the expression is 
exhausted. POS(E$=""") returns the position of the leftmost space in 
E$. POS(-E$=" ") returns the position of the rightmost space. 


When comparing alpha string variables with literal strings or 
other alpha variables (e.g., IF A$ < "ABC"), values are compared 
character by character. Trailing spaces are considered equivalent 
to HEX(20) in determining where to place each value in the collating 
sequence. The values fall at the same location in the collating 
sequence (i.e., they are equal) even if they do not have the same 
number of trailing spaces, as long as all their other characters are 
equal. For example: 


100 DIM A$4, B$5, C$5 


200 A$="ABC" 
300 B$S=HEX(41424321) /* HEX(41424321)="ABC!" */ 
400 C$="ABC " 


500 IF A$=B$ THEN 800 

600 IF A$=C$ THEN 1000 

700 PRINT "A$ NOT EQUAL TO B$ OR C$." : GOTO 1100 
800 PRINT "A$=B$: "A$; "="; BS 

900 GOTO 1100 
1000 PRINT "A$=C$: ";A$S;"=";C$H 

1100 END 


Output: 


A$=C$: ABC=ABC 
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5.6.4 VAL 


The VAL function requires an alpha expression as an argument. A 
digit whose value is 1, 2, 3, or 4 can be supplied as a second 
argument; if it is omitted, a value of 1 is assumed for the second 
argument. 


The VAL function extracts up to four characters from the alpha 
expression, depending on the value of the second argument, and 
returns a decimal integer that is equivalent to the binary value of 
the extracted character(s). 


VAL(A$) or VAL(A$,1) simply returns the decimal value of the 
ASCII code for the first character of A$. For instance, VAL("A",1) 
is 65, VAL("B",1) is 66, and so on. The value ranges from 0 through 
255. The value returned is the decimal equivalent of character's 
binary ASCII code, not the hexadecimal value. 


VAL(A$,2) returns an integer whose value is: 

(code for lst char.)*256 + (code for 2nd char.) 
It is in the range 0 through 65535. 

VAL(A$,3) returns a value between 0 and 16777215: 


(code for lst char.)*65536 + (code for 2nd char.)*256 + 
(code for 3rd char.) 


VAL(A$,4) computes the following value: 


(code for lst char.)*16777216 + (code for 2nd char.)*65536 + 
(code for 3rd char.)*256 + (code for 4th char.) 


This computation requires all 32 bits of the integer; in 
addition, overflow can occur, causing the result to be a negative 
integer. The value of the result ranges between -2147483648 and 
2147483647, inclusive. 


The BIN function can be used to extract characters from an 
integer expression containing their binary values, reversing the 
operation performed by VAL. 


5.7 LOGICAL EXPRESSIONS 


The alpha operators and functions discussed so far have all 
involved manipulation of single characters and strings of characters. 
It is also possible to manipulate individual bits within the bytes 
that represent stored characters. This is done in a special type of 
alpha-expression, called a logical expression, that can be used only 
on the right-hand side of an assignment (LET) statement. 


Logical expressions are alpha-expressions that contain any of 
several logical operators and have the general form: 


[operator] operand [operator operand] ... 


where operator is one of ADD[C] 
AND 
OR 
XOR 
BOOLh 


and where operand is an alpha-expression or ALL(alpha-expression). 


Note that concatenation (&) and parentheses are not allowed 
within logical expressions. 


5.7.1 Evaluation of Logical Expressions 


A statement of the form "LET alpha-receiver = logical 
expression" is evaluated as follows: 


l. If the expression begins with an operand, the receiver is 
assigned that operand (i.e., as in a simple LET statement). 


2. From left to right, the next operator operates on the 
operand to its right and the receiver (i.e., the receiver is 
used as an operand). In all cases, the defined lengths of 
both arguments are used, with the operation proceeding one 


byte at a time as follows: 


a. AND, OR, XOR, BOOLh --— The operation proceeds one byte 
at a time from left to right. If the operand is shorter 
than the receiver, the remaining characters of the 
receiver are unchanged. If the operand is longer than 
the receiver, the operation -stops when the receiver is 
exhausted. The specific effects of these operators are 
described in the next section. 


b. ADD, ADDC -—-— The operation proceeds one byte at a time 
from right to left. If the operand and receiver are not 
the same length, the shorter one is left-padded with hex 
zeros. The result is right-justified in the receiver, 
with high-order characters truncated if the result is 
longer than the receiver. The specific effects of these 
operators are described in the next section. 


3. The receiver always gets the result of the operation; Step 2 
is then repeated until all operator-operand pairs are used 


up. 
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Part of an alpha variable can be operated on by using the STR 
function to specify a portion of the variable. For example, 


100 STR(A$, 3, 2) = ADD B$ 


operates only on the third and fourth bytes of Af. 


5.7.2 Logical Operators 


In the following examples, assume A$ has a defined length of 2 


bytes. 


AND -— 


OR -- 


XOR -— 


BOOLh-— 


ADD —- 


ADDC -- 


Logically ANDs the two operands, one byte at a time, as 
indicated in Table 5-1. For example: 


LET A$ = HEX(OFOF) AND HEX(0OFFO) 
Result: A$ = HEX(OFOO) 


Logically ORs the two operands, one byte at a time, as 
indicated in Table 5-1. For example: 


LET A$ = HEX(OFOF) OR HEX(OFFO) 
Result: A$ = HEX(OFFF) 


Logically exclusive-ORs the two operands, one byte at a 
time, as indicated in Table 5-1. For example: 


LET A$ = HEX (OFOF) XOR HEX (OFFO). 

Result: A$ = HEX(OOFF) 

Performs one of 16 logical operations specified by the 
value of the hexadecimal digit h. See the entry in Part 
II under BOOLh for a description and examples of these 
operations. 

Adds the binary values of the operands, one byte at a 
time, with no carry propagation between bytes. For 
example: 

LET A$ = HEX(0123) ADD HEX(OOFF) 

Result: A$ = HEX(0122)- 

Adds the binary values of the operands, one byte at a 
time, with carry propagation between bytes (like two 
long binary numbers). For example: 


LET A$ = HEX(0123) ADDC HEX(0O0FF) 


Result: A$ = HEX(0222) 
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Table 5-1. Logical Operations 


. Operand 1 Operand 2 
Logical operator Bit = Bit = 


AND (Result = 1 if both 
operand bits = l. 
Otherwise, result 

= 0.) 


(Result = 1 if either 
or both operand bits 
=1l. Otherwise, 
result = 0.) 


(Result = 1 if one 
or the other but 
not both operand 
bits = 1. Otherwise, 
result = 0.) 


5.8 SUMMARY OF ALPHANUMERIC DATA FORMATS AND TERMS 


5.8.1 Alphanumeric Length 


1. Actual or Current Length (in bytes) 
(as determined by LEN function) 


a. Alpha Variable -- Does not include trailing blanks. If 
all blank, length = 1. 


b. Alpha Array String -- Like a single long alpha variable. 


c. Alpha-expression --— Length = sum of actual lengths of 
the concatenated arguments. 

d. STR function --— Length is the number of characters 
extracted, including trailing blanks. 

e. KEY function -- Length is the key length specified in 
SELECT. 

£. Literal -— Length is the number of characters within 


quotes or the number of hexadecimal digit pairs in HEX. 


g. FS function -—- Length = 2. 
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2. 


5.8.2 


Le. 


DATE function -~ Length = 6. 


TIME function -- Length = 8. 
MASK function —- Length = 2. 
BIN function --— Length as specified by second argument 


of BIN (1, 2, 3, or 4; default=1). 


Defined Length 


a. 


d. 


Alpha Variable -- As specified in DIM, COM, or most 
recent MAT REDIM. (Default = 16.) 


Alpha Array String -- Product of 3 dimensions (e.g., 
row, column, element length) in DIM, COM, or most recent 
MAT REDIM. (Default 10 x 10 x 16.) 


Alpha-expression -- Except alpha variables and alpha 
array strings. Same as actual length. 


All Other Alpha Forms -—- Same as actual length. 


Alphanumeric Terms 


| letter 
Alpha Scalar Variable: letter < digit oe. 
underscore 


(not to exceed 64 letters, digits, and underscores) 


letter 
Alpha Array Name: letter digit Kee oS 
underscore 


(not to exceed 64 letters, digits, and underscores) 


letter 
Alpha Array-designator: letter digit woe) «=680) 
underscore 


(not to exceed 64 letters, digits, and underscores) 


letter 
Alpha Array Element: letter digit ...-$(exp[,exp]) 
underscore 


(not to exceed 64 letters, digits, and underscores) 


alpha array variable 


Alpha Variable: jie scalar wriabie } 


letter 
6. Alpha Array String: letter digit ee) «=680) 
underscore 


(not to exceed 64 letters, digits, and underscores) 


(Treated as a single long alpha variable) 


7. Literal: "  JTany any ” 
character character 
except except 

ity 8 
: any any : 
character character 


except except 


HEX(hh[{hh]...) 
8. h: a hex digit (0,1,2,...,9,A,B,C,D,E, or F) 


9. Alpha Receiver: alpha-—variable 
STR(alpha receiver[,[exp][,exp]]) 
alpha array string 
| KEY (file-expression [,exp]) 


10. Alpha Expression: alpha-receiver 
(or Alpha-exp) literal 

DATE function 
TIME function 
BIN function 
MASK function 
FS (£11le-expression) 
alpha-exp & alpha-—exp 
(alpha-—expression) 
STR (alpha-exp[,[exp][,[exp]]]) 


11. Logical Expression: 
[operator] operand [operator operand] 


where: 
ADD[C] 
AND 

operator = BOOLh operand = }alpha-expression 
OR ALL function 
XOR 
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Alphanumeric Operations 


1. The following applies to alpha values used in any BASIC 
functions or operations: 


a. 


In statements that can alter the values of variables 
(e.g., LET, COPY), values of alpha expressions that are 
not acting as receivers are copied to a temporary 
location*; the value in the temporary location is then 
used in whatever operations are specified. This 
includes alpha receivers enclosed in parentheses. 


Alpha receivers, on the other hand, are never moved, but 
are operated on in place, except in the TRAN statement 
(described in Part II). The differences in results that 
can occur depending upon whether an expression is a 
receiver are most apparent in multiple assignment (LET) 
statements; LET statements incorporating ADD, AND, OR, 
XOR, BOOLh; and COPY statements. 


For example, 

100 LET A$="A" 

200 LET BS="B" 

300 LET A$,B$,C$ = AS & BE /*THIS IS A MULTIPLE "LET"*/ 
400 PRINT A$,B$,C$ 


prints: 


AB AB AB 


An expression is said to be "acting as a receiver" in the context 
of a particular statement if it is syntactically a receiver (see 
Section 3.2) and is also being assigned a new value in that 
statement. 


When statement 300 is executed, the value of A$ ("A") is 
concatenated with the value of B$ ("B") and the result 
("AB") stored in a temporary location. This string is 
then copied from the temporary location into A$, B$, and 
C$ sequentially. If a temporary location were not used, 
statement 300 would be equivalent to 


300 LET A$ = A$&B$ : LET BS = AFS&BS : LET C$ = ASEBS 
and the program would print 
AB ABB ABABB 


b. In general, any operation requiring character comparison 
or movement is done one character at a time. This 
applies to each of the functions listed above. 


TRAN always moves the translation alpha expression to a 
separate translate table inaccessible to the user. Thus, 
TRAN can never translate its own table. 


Statements that perform multiple assignments always assign 
values from left to right. This applies particularly to 
LET, INPUT, ACCEPT, GOSUB'(), READ, and GET. This can be an 
important consideration, especially when receivers in the 
same location are specified more than once in the receiver 
list. 
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CHAPTER 6 
CONTROL STATEMENTS 


6.1 INTRODUCTION 


A VS BASIC program is normally executed in ascending line-number 
sequence, with multiple statements on a line executed from left to 


right. 


VS BASIC also provides a number of statements, called 


control statements, that can be used to alter the normal sequence of 
execution. 


FOR. ..NEXT INPUT (some cases) 
IF...THEN...ELSE ACCEPT (some cases) 
ON...GO TO STOP 


ON. . .GOSUB Unusual condition and 

GOTO error/data conver-— 
Sion exit clauses 
for some statements 


Figure 6-1. BASIC Control Statements 


Control statements provide BASIC with the following facilities: 


iL. 


Halting Execution -- END, if encountered in a _ program, 
terminates program execution and returns control to the 
Command Processor or to the invoking program or procedure. 
If encountered in a subroutine, END returns program control 
to the calling program (see Number 3). STOP. temporarily 
halts execution until the user presses the ENTER key or, 
under defined conditions, one of the program function keys. 


INPUT, ACCEPT, and STOP temporarily halt execution to enable 
the program user to supply the program with run time data, 
or, under defined conditions, to press a program function 
key. These statements are discussed in Chapter 7 and under 
their separate entries in Part II. 


2. Unconditional Program Branching ~- GOTO transfers control to 
the line number or statement label specified by the GOTO 


statement. The GOTO statement is discussed under its entry 
in Part II. 


3. Conditional Branching -- IF...THEN...ELSE enables’ the 
program to test a relationship -- the operand of the IF 
clause -- and branch according to the result of the test. 
If the relationship is true, the THEN clause is executed and 
the ELSE clause is not. If the relationship is not true, 
the ELSE clause (or in the absence of an ELSE clause, the 
next sequential executable statement) is executed and the 
THEN clause is not. The IF statement is discussed under its 
entry in Part II. 


4. Branching to Subroutines -- GOSUB, GOSUB', and CALL transfer 
control to various kinds of subroutines. After their 
execution, control can be returned to the main body of the 
program by RETURN or END. GOSUB and GOSUB' are discussed 
under their entries in Part II; subroutines are discussed in 
Section 6.3, Section 6.4, Section 6.5, and under the entries 
for the various statements in Part II. 


5. Looping -—- A useful feature of BASIC is its ability to 
execute a defined section of code repeatedly. This section 
of code is called a loop. BASIC provides a pair of 
statements, FOR and NEXT, that automatically mark a loop and 
determine the number of times it is executed. FOR and NEXT 
are discussed under their entries in Part II. 


6. Unusual Condition Exits --~ VS BASIC provides a number of 
exits for data error and end-of-data conditions that would 
otherwise result in termination of a program. These include 
the DATA, IOERR, and EOD (end-of-data) clauses in the file 
I/O and CONVERT statements. These clauses in file I/0 
statements are discussed in Section 8.6, and in the 
appropriate entries in Part II. 


6.2 STATEMENT LABELS 


Any statement in a VS BASIC program can be identified by a 
statement label that immediately precedes it. A statement label (or 
simply a “label") can be any string of up to 64 letters, digits, and 
underscores, provided that the first character is a letter and that 
the string is not a VS BASIC reserved word (see Section 2.2 and 
Appendix A). 


Using labels, a programmer can write statements that alter the 
flow of program execution without having to keep track of line 
numbers. For example, instead of writing GOTO 100 (where 100 is a 
program line number), the programmer can write GOTO PART2, where 
PART2 is a statement label. In this case, execution continues with 
the first executable statement following the label PART2. A label 
can occur alone on a line, or at the beginning, middle, or end of a 
line containing one or more statements. If a label is followed by 
one or more statements on the same line, the label and the following 
statement must be separated by a colon. If a label occurs alone on 
a line or at the end of a line, the colon is optional. 


The following are some examples of correct and incorrect usage 
of statement labels: 


CORRECT : 


1. 500 PART2 
600 PRINT "ENTER DATA FOR PART 2" 
(Label is PART2.) 


2. 900 FIRST TIME : RAISIN=RAISIN+1 : RETURN 
(Label is FIRST TIME.) 


3. 100 LET CAT=(10*X)/PI : FIRST : READ Z 
(Label is FIRST.) 


4. 300 READ NAME$, STREETS, PHONES : HENRY 
350 EXCH$=STR(PHONES, 5, 3) 
(Label is HENRY.) 


INCORRECT : 


1. 200 NEXT : IF KRISP = 99 THEN 6100 
(NEXT is the verb of an executable statement used to 
terminate a FOR...NEXT loop and is thus a reserved word. 
Reserved words cannot be used as labels.) 


2. 700 LAST ONE 
800 FOR I=1 TO 100 : READ FRED(I) : NEXT I 
(LAST ONE: labels cannot contain embedded spaces. The 
compiler would interpret this as being a single label (LAST) 
and would expect it to be followed by a statement terminator, 
such as a colon or the end of the source program line.) 


3. 400 LET B(J)=SQR(X(J)) : LABEL PRINT B(J) 
(LABEL should be separated from the following statement 
(PRINT) by a colon.) 


4) 1000 CAT&MOUSE : IF CS>MS THEN 1700 
(CAT&MOUSE contains a character (&) that is not a letter, 
number, or underscore and is thus invalid as a label.) 


5) 5200 2ND_TIME : GOSUB 7520 
(2ND TIME: the first character of any label must be a 
letter.) 
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6.3 SUBROUTINES 


A subroutine is a group of program lines that can be invoked from 
any point in a program to perform a specific task. When execution of 
a subroutine is complete, processing normally returns to the point in 
the program from which the subroutine was invoked. The same set of 
instructions can be used in many different points in a program, with 
control returning (if desired) to the part of the program that 
called the subroutine. 


VS BASIC provides internal and external subroutines. Internal 
subroutines are included as part of the code in the main BASIC source 
file. They are invoked by a GOSUB or GOSUB' statement or, under 
certain circumstances, by pressing an appropriate PF key while 
execution is halted by INPUT or STOP. Subroutines invoked by GOSUB' 
or a PF key are marked in the source file by a DEF FN' statement. 
Subroutines invoked by GOSUB need not be marked; GOSUB transfers 
control to a specific line number or statement label. 


External subroutines are written as independent files, beginning 
with a SUB statement. After compilation, they are linked to the main 
program through the LINKER utility (see Subsection 1.4.3, Subsection 
6.5.3, and the VS Program Development Tools). The main program 
invokes external subroutines by means of the CALL statement. 
External subroutines can be linked to any number of calling programs, 
making them a useful way to code routines that can be used by more 
than one program. An external subroutine has to be coded only once. 
If it is later changed, it has to be recompiled only once, and the 
calling programs do not have to be modified. 


6.4 INTERNAL SUBROUTINES 


VS BASIC provides three ways of invoking an internal subroutine: 
GOSUB, GOSUB' and pressing program function keys at execution 
time. The following subsections provide brief summaries of these 
statements. A full discussion of each statement can be found under 
the appropriate entry in Part II of this manual. 


6.4.1 GOSUB Subroutines 


The GOSUB statement branches to a line number or a statement 
label. For example: 


500 GOSUB 2000 900 GOSUB RABBIT 


When executed, statement 500 transfers control to line 2000; 
statement 900 transfers control to the statement labeled RABBIT. 
The beginning of the subroutine need not be specially marked. Any 
valid BASIC statement can begin a GOSUB subroutine. For example: 


2000 REM THIS SUBROUTINE PRINTS THE CURRENT VALUE OF A 


2100 PRINT "A="; A 
2200 RETURN 
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When a GOSUB statement is executed, the program stores the 
location of the statement that invoked the subroutine. At the end of 
the subroutine, marked in this case by a RETURN statement, execution 
continues at the statement following the GOSUB statement on line 500. 
If the same subroutine is subsequently invoked from line 1200, 
execution continues then at the statement following the GOSUB 
statement on line 1200. The end of a GOSUB subroutine is marked by a 
RETURN or RETURN CLEAR. RETURN CLEAR causes execution to continue 
with the statement following RETURN CLEAR, instead of returning to 
the statement after the GOSUB.- 


6.4.2 GOSUB' Subroutines 


The GOSUB' statement branches to a subroutine that is marked by 
a DEF FN' statement.. For example: 


500 GOSUB'112 


This statement causes control to pass to the statement DEF 
FN'112. The range of allowable DEF FN' numbers is 0 to 255. 
Following execution of the marked subroutine, control is returned to 
the statement following the GOSUB' by a RETURN, or to the statement 
following the subroutine by a RETURN CLEAR. 


The most important difference between GOSUB and  GOSUB' 
subroutines is that the latter allow the passing of an argument list 
from the main program to the subroutine. This is useful where a 
subroutine may be called from different parts of a program to perform 
the same series of operations on different variables. For example, 
suppose one wanted to write a subroutine that would add some variable 
to the length of an alpha variable. The subroutine could be written 
as: 


5000 DEF FN'100 (STRING$, COUNT%) 
5100 PIGEON% = LEN(STRING$) + COUNT% 
5200 RETURN 


The subroutine might be called from elsewhere in the program to 
perform its operation on a string called PHONE$ and an integer 
called BOOK% by the statement 


400 GOSUB'100 (PHONE$, BOOK%) 


When line 400 is executed, implicit assignment statements are 
performed that assign the current value of PHONE$ to STRING$ and that 
of BOOK% to COUNT%. By this means, the arguments are "passed" to the 
subroutine. When the subroutine is completed (by the execution of 
the RETURN on line 5200), the sum of the value of BOOK% and the 
length of PHONES is stored in PIGEON%. 
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The same subroutine might be called again from a different point 
in the program to operate on two different variables: 


1500 GOSUB'100 (BOX$, CAR%) 
Once again, the result would be stored in PIGEON%. 


While this may appear similar to the scheme of dummy variables 
used in defining user-defined functions (see Subsection 4.4.2), there 
is one very important difference. Dummy variables in function 
definitions have no significance beyond the function definition 
itself. Thus the function can use a name as a dummy variable even if 
it is also used as a regular ("'non-dummy") variable elsewhere in the 
program, without affecting the value of that variable. The arguments 
used in defining a DEF FN' subroutine, however, are regular variables 
that are not in any way distinct from those used in the main program. 
If a variable used in a main program is also used in a DEF FN' 
subroutine, the original value of that variable is lost when the DEF 
FN' subroutine is called. Consider the following examples: 


Program 1: 


100 DUM=1 

200 X=16 

300 DEF HALF ROOT (DUM)=SQR(DUM) /2 /* FUNCTION DEFINITION */ 
400 Y=HALF ROOT(X) /* SUBROUTINE CALL */ 

500 PRINT DUM, X, Y 


Output: 
1 16 2 


Program 2: 


100 DUM=1 
200 X=16 

300 GOSUB'100 (xX) /* SUBROUTINE CALL */ 

400 PRINT DUM, X, Y 

500 DEF FN'100 (DUM) /* BEGINNING OF HALF-ROOT SUBROUTINE */ 
600 Y=SOR(DUM) /2 


700 RETURN /* END OF SUBROUTINE */ 
Output: 
16 16 2 


In the first program, DUM is used in defining the function HALF ROOT, 
which is then called to operate on the value of X. Afterwards, DUM 
retains the value it was assigned in line 100. In the second 
program, DUM is again used to define the same operation (lines 500, 
600). When the subroutine is called in line 300, however, DUM is 
assigned the value of X, thus destroying the value originally 
assigned in line 100. 


Arguments are passed in the exact order in which they appear in 
the argument lists: the first item in the GOSUB' list to the first 
item in the DEF FN' list, the second to the second, and so on. 
Arguments must correspond in type; an alphanumeric argument cannot be 
passed to a numeric receiver; and vice versa. Floating-point 
arguments can, however, be passed to integer receivers, and vice 
versa. 


6.4.3 Program Function Keys 


The VS workstation has 16 Program Function (PF) keys at the top 
of the keyboard. Each of these can be pressed alone or with the 
SHIFT key, providing a total of 32 program functions. BASIC can 
program any of the PF keys to invoke the marked subroutines. 


Subroutines invoked from the keyboard are marked by DEF FN’ 
statements, with the restriction that the DEF FN' numbers for 
subroutines accessible by the PF keys must be between 1 and 32 
(instead of 0 to 255, as with the GOSUB' statement). A DEF FN' 
subroutine can be invoked from the keyboard whenever execution has 
been temporarily halted by a STOP or INPUT statement. At this time, 
pressing a PF key causes control to pass to the DEF FN' subroutine 
corresponding to that PF key. For example: 


500 STOP 


2000 DEF FN'1l 


Pressing PF1 when execution is halted by the STOP at line 500 invokes 
the subroutine marked by DEF FN'l. Pressing ENTER causes the normal 
sequence of execution to continue with the statement following STOP. 
Pressing a PF key for which there is no corresponding DEF FN' 
subroutine in the program causes the workstation alarm to sound; the 
key is ignored. 


Keyboard subroutines operate in the same manner as _ GOSUB' 
subroutines, with one exception. A RETURN statement passes control 
back to the STOP or INPUT statement, instead of to the following 
statement. Thus, DEF FN' subroutines can be invoked repeatedly from 
a STOP or INPUT statement. 


NOTE 


To avoid unintended transfers to marked subroutines, it 


is recommended that numbers 1 through 32 be used only 
for those subroutines meant to be invoked by PF keys. 


6.5 EXTERNAL SUBROUTINES 


A second class of subroutines is not contained in the body of the 
program (the same file), but instead resides in a separate file. 


Such subroutines, referred to as "external subroutines" | or 
"subprograms," are defined with the SUB statement and invoked with 
the CALL statement. In general, a BASIC source file can contain 


either a main program or a subprogram. Subprograms are distinguished 
from main programs by the fact that the first statement of a 
subprogram, other than the REM statement, is the SUB statement. 


6.5.1 Operation of External Subroutines 


The SUB statement declares a program to be a subroutine and 
specifies the subroutine name, allowing it to be referenced in CALL 
statements. The CALL statement transfers control from one program 
(the calling program) to the beginning of another program (the 
external subroutine). The external subroutine is referenced using 
the name specified in the SUB statement. The point at which the 
CALL statement occurs in the main program is saved, so that control 
can later return to that point. A subroutine can contain one or 
more CALL statements with which it can call other subroutines. A 
subroutine cannot call itself. 


When control is passed to an external subroutine by a CALL 
statement, the normal sequence of execution is followed in the 
subroutine until an END statement is encountered. Control then 
returns to the statement following the last CALL statement executed. 


In a calling program, a CALL statement invokes an entire 
sequence of statements in whatever order they are contained in the 
subroutine without affecting the overall flow of control in the 
calling program. 


In both form and _ operation, external subroutines are 
self-contained programs; they must, however, begin with the SUB 
statement and, in some cases, operate on values obtained from the 
calling program. Once the external subroutine has been called, the 
only way execution can pass back to the calling program is by the 
execution of an END statement. All branching instructions (GOTO, 
IF...THEN...ELSE, GOSUB, GOSUB', etc.) in an external subroutine 
refer to line numbers or statement labels within that subroutine. 
For example, it is not possible to GOTO a statement outside the 
subroutine. Note that this differs from internal subroutines, which 
can branch to any portion of the calling program. 
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6.5.2 Form of External Subroutine Calls and Definitions 


An external subroutine is any BASIC program having a SUB 
statement as its first statement (other than REM). The general form 
of the SUB statement is: 


SUB "name"" [ [ADDR] (arg[, arg] ... ) ] 


where "name" is the name of the subroutine, consisting of any string 
of 1 to 8 alphabetic’ or numeric characters (including @, #, and $). 
The presence or absence of the word ADDR specifies the way in which 
the optional arguments are to be passed between the calling program 
and the subroutine. 


An external subroutine is called by a CALL statement in another 
program. The general form of the CALL statement is: 


CALL "name" [ [ADDR] (arg[, arg] ... ) ] 
where "name" is the name specified in the SUB statement of the 


subroutine being called. Again, the word ADDR and the optional 
argument list specify the form of argument passing to be used. 


NOTE 


The name of the subroutine is defined by the literal in 


the SUB statement, not by the name of the file containing 
the subroutine. These two names need not be the same. 


6.5.3 Compiling, Linking, and Running 


Each main (calling) program and each external subroutine is 
entered into a separate source file using the EDITOR. The BASIC 
compiler must be called separately for each program and external 
subroutine to produce an object file for each one. Thus, in writing 
a program that uses two external subroutines, three source files are 
created (one for the calling program and one for each of the two 
subroutines). The BASIC compiler is then run three times (once to 
compile each of these files), resulting in three object files. 


Before the program and subroutines can be run, the object 
programs must be linked together. Linking is the process of merging 
multiple object modules into one. The LINKER utility is used to 
link programs and external subroutines. The LINKER is run from the 
VS Command Processor; it resolves subroutine name references between 
object modules to produce a single object module that can then be 
run. The LINKER asks the user for the names of all the object files 
to be linked together and then requests a name for the single output 
file. The files are then linked and the final output file is 
generated. 
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The original program and subroutines can then be run from the 
Command Processor as one would run any other program, using the 
program name specified as the output file for LINKER. For further 
details on how to use LINKER, see the VS Program Development Tools. 


6.5.4 Passing Values to External Subroutines 


Since calling programs and external subroutines are written and 
compiled as separate programs, there must be a way to pass data 
between them if subroutines are to process any of the data used in a 
calling program. In BASIC, values are passed in one of two ways: 


1. The values can be made arguments of the subroutine. An 
argument of a subroutine is a value that can be operated on 
by action of the subroutine. Arguments are enclosed in 
parentheses following both the CALL and the SUB statements. 


2. The values can be stored as common variables (or "placed in 
common"). Common variables are variables that are stored in 
a particular area of memory accessible to all programs and 
subroutines that are run together. Variables are placed in 
common using the COM statement (see Subsection 6.5.4 and the 
COM statement entry in Part II). 


Arguments 


The arguments in a SUB statement must be variables, array 
designators, or file numbers. These arguments are dummy variables 
(like those in user-defined function definitions; see Subsection 
4.4.2) that indicate the names that will be used in the subroutine 
to refer to the arguments specified by any particular CALL to that 
subroutine. The actual names used for dummy variables are 
Significant only within the subroutine and need have no connection 
with names used in a_ calling’ program, except for type 
correspondence, described in Subsection 6.5.6. 


Arguments of a CALL statement must be numeric or alpha 
expressions, or file expressions. Their values are passed one-—by-—one 
to the dummy variables in the SUB statement of the external 
subroutine at run time. The value of the first expression in the 
CALL argument list is passed to the first dummy variable in the SUB 
statement, the second to the second, and so on. 


Values are passed back to the calling program when’ the 
subroutine ends, provided the arguments in the CALL statement are 
receivers. A subroutine cannot manipulate or examine any value used 
in the calling program unless it is passed through an argument list 
or common storage. For example: 


Calling program: 


100 A=10 : X=500 
200 CALL "DOUBLE" (A) 
300 PRINT A, X 


Subroutine: 


100 SUB "DOUBLE" (X) 
200 X=2*X 
300 END 


Output: 
20 500 


Note that although both programs use variables called X, only the 
value of A is passed to the subroutine's X since it is the only 
argument specified in the CALL statement. The subroutine's X is a 
dummy variable that, in this case, is temporarily assigned the value 
of A. The subroutine doubles the value of the argument (in this 
case, A) and then passes this value back to the calling program when 
the subroutine ends. The value of the variable called X in the 
calling program remains unchanged. 


When an array or an alphanumeric value is used as an argument of 
an external subroutine call, BASIC normally passes a descriptor of 
the value to the subroutine, rather than the actual value. A 
descriptor is a set of data that specifies: 


1. The type of the argument (alpha scalar, alpha array, integer 
array, or floating-point array). 


2. The length of the value if it is alphanumeric (element 
length if an alpha array). 


3. The dimensions of the argument if it is an array. 


4. The address in memory at which the value is stored (a 
"pointer" to the value). 


This scheme of passing descriptors between calling programs and 
subroutines is normally used when BASIC subroutines are called from 
BASIC programs. Subroutines and calling programs written in other 
languages (e.g., COBOL, Assembler) use a different scheme in which 
only the address of the value is passed. To enable BASIC programs 
and subroutines to be linked and run with programs and subroutines 
written in either BASIC or some other language, two forms of CALL 
and SUB are available. 


6-11 


1. Non-ADDR Form -- The standard<BASIC argument-passing scheme 
that passes/accepts the descriptors constructed for arrays 
and alpha-expressions. With this form, any dimensions or 
lengths specified within the SUB program are ignored, since 
they are specified by the descriptors. Only the 
vector/matrix/scalar distinction is significant. Examples: 


700 CALL "INVOICE" (PN%(), Q%()) 
100 SUB "INVOICE" (PART NO%(), QUANTITY%()) 


2. ADDR Form -- Generally used when either the calling program 
or the subprogram is non-BASIC. Its effect differs depending 
on the statement in which it is used: 


CALL: The ADDR form of CALL causes all argument-—passing to 
be done via pointers to the actual values; 
descriptors are not constructed. This method of 
argument-passing properly passes arguments to 
non-BASIC (e.g., COBOL) programs, which always 
assume that there are pointers directly to _ the 
data. Example: 


900 CALL "PLOT" ADDR (H$, V$) 


SUB: The ADDR form of SUB causes the program to assume 
that argument—passing was done as described in CALL 
(i.e., without descriptors). (For example, such 
calling may have been done from a COBOL program. ) 
This implies, however, that the dimensions and 
lengths used must be those specified within the SUB 
subroutine. Thus, these dimensions and lengths (or 
defaults, if omitted) are significant, unlike in the 
non-ADDR form. Example: 


100 SUB "PLOT" ADDR (X$, Y$) 
200 DIM X$ 100, Y$ 100 


NOTE 


Languages other than BASIC use different internal formats 
for representing numeric data. Numeric data to be passed 
between BASIC and non-BASIC program modules must be 
converted to the appropriate format. Programmers 


planning to write BASIC programs or subprograms that call 
or are called by programs in other languages should see 
Appendix D for information on compatibility of numeric 
data formats and data conversion routines. 


Common Variables 


The COM statement can make certain variables accessible to all 
programs and subroutines that are linked and run together. A COM 
statement must appear in all of the programs and subroutines that 
are to be run together if the programs are to manipulate or examine 
any of the same data. The COM statement in each program must 
precede any reference to any variable that is to be stored in common. 


The COM statement consists of the word COM followed by a list of 
alpha or numeric scalar or array names. Array names can be followed 
by one or two integers in parentheses giving the dimensions of the 
array. If these dimensions are omitted, the default dimensions are 
10 rows by 10 columns. Alphanumeric scalars or array names can be 
followed by an integer giving the length, in bytes, of the scalar or 
the elements of the array. If the length indicator is omitted, the 
default length is 16 bytes. For the general form of the COM 
statement, see Part II. 


As is true with passed arguments, the names used for common 
variables in a subroutine need not correspond with those used in the 
calling program, except in type (e.g., integer, alpha, array, etc.). 
Common variables referenced in calling programs and subroutines are 
associated with each other by their position in the COM statements. 
This means that, in many cases, a subroutine may require a COM list 
that includes variables not actually used by the subroutine, simply 
to indicate where in the common area certain needed variables are 
stored. For example, in 


100 COM A$5, B%, C(100), D 
200 CALL "SUB1" 
300 CALL "SUB2" 


suppose that "SUB1" is a subroutine that performs some operation on 
the 100-element array called C() in the main program, and that "SUB2" 
operates on the other variables in the COM list (line 100). Even 
though "SUB1" does not need to access A$ and B%, they must be 
accounted for in a COM statement so that the subroutine can find the 
100-element array in the common area. If 


100 SUB "SUB1" 
200 COM X(100) 


was written, the subroutine would look for the 100-element array, 
called X() in the subroutine, at the beginning of the common area. 
In fact, the first item in the common area is a 5-byte character 
string, called A$ in line 100 of the calling program. The subroutine 
would read the beginning of A$ as the beginning of its 100-element 
array, which would not produce the intended results when the program 
is run. A correct form for the subroutine's COM statement is: 


200 COM M$5, N%, X(100) 
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In this case, even though "SUB1" actually needs to use only array 
X(), it looks for it after a 5-character alpha string and an integer 
in the common area. The last item in the common area, a 
floating-point variable called D by the calling program, need not be 
specified in the subroutine COM statement since it occurs in the 
common area after the only variable needed by the subroutine. 


NOTE 


No variable name occurring in the argument list of a SUB 
statement can occur as another argument of the same SUB 


statement or in a COM statement in that subroutine. 
Calling programs can, however, pass common variables to 
a subroutine as arguments in a CALL statement. 


6.5.5 Initialization of Subroutine Variables 


The variables in the argument list will receive their arguments 
from the calling program when the subroutine is called. All other 
variables (local variables) are initialized when the BASIC program 
is first executed. String variables are initialized to all spaces; 
integer and floating-point variables are initialized to zero. This 
initialization, however, occurs only once in the execution of a 
BASIC program. 


Local variables are not reinitialized on subsequent calls. One 
application of this feature is as follows: 


100 SUB "HOOPOE"(arg,arg,...) 

200 REM Let I be a variable which is not in the argument 
250 REM list above. 

300 IF I<>0 THEN 700 

400 REM Place here statements which are to be 

450 REM executed only the first time the subroutine 

500 REM is ever called. 

600 LET I=1 

700 REM The subroutine continues. 


9900 END 
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The first time the subroutine is executed, the variable I is set 
equal to zero (as are all others not in the argument list). When 
line 300 is executed, the condition of the IF statement is not 
satisfied, and execution proceeds through line 400 and the following 
lines. In line 600, the value of I is set to 1. On all subsequent 
calls to the subroutine, I retains this value; when line 300 is 
executed during a subsequent subroutine call, the IF condition is 
satisfied and the statements between lines 300 and 700 are skipped. 


6.5.6 Argument Types 


As discussed above, the name of an argument passed to a 
subroutine is not significant in making the connection between 
calling-program variables and subroutine variables. What is 
Significant is the argument's position in the argument list or common 
block. Thus, the variable name listed first in the parentheses in 
the SUB statement or first in a COM list is the name used by the 
subroutine to refer to the first argument passed by the CALL 
statement or specified in the calling program's COM statement. The 
second variable name is linked to the second argument in the CALL 
statement or COM list, and so on. For example: 


15700 CALL "DANAUS" (A,B,C,D,E) 
100 SUB "DANAUS" (1I,J,K,A,B) 


In this example, the variable name A in the subroutine refers to the 
variable D in the calling program. If the subroutine intends to 
access the calling program's variable A, it must use the symbol I. 
The same is true if variables are passed through common storage: 


100 COM A, B, C, D, E 


2300 CALL "PLUMBER" 


100 SUB "PLUMBER" 
200 COM I, J, K, A, B 


If a receiver is placed in the argument list of a CALL statement, 
the subroutine can transmit a value back to the calling program by 
assigning a value to the corresponding variable in the argument list 
of a SUB statement. However, an expression of arbitrary complexity 
can appear in the argument list of the CALL statement. If the 
expression is not a receiver, the subroutine cannot return a modified 
value for that argument to the main program. The subroutine can use 
the corresponding variable from the SUB statement as a receiver; 
doing so produces the usual effects during the duration of that call 
to the subroutine, but no detectable effects after the subroutine 
returns to the calling program. For example, constants, literals, 
and complex expressions can occur in the argument list of a CALL 
statement. This precludes the possibility of the subroutine's 
returning a value to the calling program by the use of that 
particular element. 
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Whether a receiver or an expression occurs as an argument in a 
CALL statement, its type must match the type of the corresponding 
argument in the SUB statement it calls. 


If the n-th ...then the n-th argument of 
argument of a SUB any CALL statement that 
statement is... calls it must be... 

an alpha scalar, an alpha-expression. 

such as: X$ 

an integer scalar, an integer expression. 


such as: X% 


a floating-point a floating-point expression. 
scalar: X 


an array an array-designator of the same type 
designator: X$() (integer, string, floating-point). 
a file-number: #3 a file-expression selected by the 


calling program or passed to it as 
a parameter. 


Note that BASIC does not implicitly convert a numeric quantity ina 
CALL statement from integer to floating-point, or vice versa, to 
make its type match the type in the argument list of a SUB statement. 


Entire arrays can be passed from a calling program to a 
subroutine. Only the array-designator (for example, E() or M$()) is 
used as an argument in the CALL statement. The SUB statement must 
contain, in the corresponding position, an array-designator of the 
same type (floating-point, integer, or string) as the designator in 
the CALL statement. The designator used in the SUB statement 
declares the name by which that array will be referenced in the 
subroutine. Subroutines can also access arrays used by the main 
program if the array is declared in COM statements in both programs, 
as with scalar variables. 


An alpha array string (see Section 5.3) cannot be passed to a 
subroutine in the usual manner. If the array string M$() occurred 
as an argument in a CALL statement, it would be interpreted as an 
array—designator for the array M$, and not as the array string. An 
array string can be passed to a subroutine by using the expression 
STR(M$()) as an argument in the CALL statement. 


y 


NOTE 


Array strings longer than 256 bytes are truncated. 
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The number of subscripts associated with a variable must be 
consistent between the calling program and the subroutine. If the 
array passed is two-dimensional (a matrix), it must be used as a 
matrix in the subroutine. If it is one-dimensional (a vector), it 
must be used as a vector in the subroutine. A DIM statement should 
appear in the subroutine to declare each array argument as either a 
vector or a matrix. In the DIM statement, the supplied dimensions 
are irrelevant; the actual upper limits are those specified in the 
array descriptor passed from the calling program. In fact, a MAT 
REDIM statement (see Subsection 9.2.4) can occur in a subroutine, and 
the redimensioning of the matrix remains in effect when control 
returns to the calling program, unless the subroutine is ADDR type 
(see Subsection 6.5.4). In that case, the effects of the MAT REDIM 
last only until control returns to the calling program. 


NOTE 


If an array whose designator does appears in the SUB 


statement does not appear in a DIM statement in the 
subroutine, it is assumed to be a matrix. 


A file-expression can be passed from a calling program to a 
subroutine. For instance, if CALL "SUBROU"(#2) calls SUB 
"SUBROU" (#1), then the subroutine can perform input and output on 
file #1 (e.g., READ #1 or WRITE #1). The actual file used is the 
file that the calling program refers to as #2. Unless linkage is 
made in this manner, any file selected by the calling program is 
inaccessible to the subroutine, and any files selected by the 
subroutine are inaccessible to the calling program. Files can be 
selected by the subroutine whether or not a file with the same number 
was selected by the calling program. 


6.5.7 Use of External Subroutines 


External subroutines may be preferable to internal GOSUB or 
GOSUB' subroutines. The reasons for this are: 


1. A program may be more manageable when broken down into 
separate subroutines in separate files. Division into 
subroutines may reflect the logical division of function 
within a program. 


2. A file containing a subroutine can be linked in with several 
different main programs if the subroutine performs a task 
common to all the main programs. If changes are made to the 
subroutine, there is only one copy of the source file for 
that subroutine that has to be updated. None of the source 
files for the main programs have to be modified. 
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BASIC programs can call subroutines written in other 
languages as well as in BASIC; subroutines can also be 
written in BASIC to be called by programs in other 
languages. Thus, the CALL and SUB statements form BASIC's 
primary interface to other languages, such as COBOL and 
Assembler. 
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CHAPTER 7 
WORKSTATION AND PRINTER INPUT/OUTPUT 


7.1 INTRODUCTION 


VS BASIC contains a group of statements to facilitate I/0 
operations to the workstation and printer. These statements enable 
the program to receive and validate operator-entered data from the 
workstation, and to create formatted screen output for display at 
the workstation and formatted print output for the printer. (VS 
BASIC also supports output to the printer through printer files. 
See Subsection 8.2.2 for a discussion of printer files.) 


7.1.1 Output 
The statements intended purely for data output are: 


PRINT -- Used to print data on the printer, or display data at 
the workstation, one line at a time. The output device is 
determined by a SELECT statement. The data can be directed to 
specific positions on the workstation screen with the AT clause, 
or can be formatted with a USING clause and an auxiliary 
formatting statement (see Section 7.4). The screen is not 
cleared before the data are displayed. For a general 
description of the PRINT statement, see Part II. : 


DISPLAY -- Used to direct a formatted display to the 
workstation, using the entire screen. DISPLAY clears the screen 
before beginning data output so that the new display is 
constructed only of the contents of the DISPLAY statement. The 
output of DISPLAY is intended only for the workstation screen, 
and cannot be directed to the printer. For a description of the 
operation of the DISPLAY statement, see Section 7.4. 


All VS BASIC input statements can also be used to some extent to 
direct data or messages to the workstation. None of this output, 
however, can be directed to the printer. The INPUT and STOP 
statements can each be used to send a one-line message, with no 
control over data format or position on the screen. The ACCEPT 
statement can also output an entire screen of data and literal 
messages in the same manner as DISPLAY. For descriptions of the 
INPUT and STOP statements, see Part II of this manual. ACCEPT is 
discussed in Section 7.5. 
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7.1.2 Input 
The statements used for data input are: 


INPUT -- Used to receive data entered from the keyboard on a 
line-by-line basis. A message inserted in an _ INPUT 
statement is displayed before the question mark INPUT 
automatically displays. PF keys can be used in response to 
an INPUT statement to initiate a branch to a *marked 
subroutine (see Subsection 6.4.3). 


ACCEPT —- Used to create a formatted display using the entire 
screen (the screen is cleared when ACCEPT begins execution) 
and then receive and validate data entered by the operator 
in response to this display. Current values of receivers in 
an ACCEPT statement are displayed, and can be altered by the 
user. ACCEPT can control positioning of data and literals 
on the screen, as well as format and display mode of data 
(bright, dim, flashing, etc.). Data entered to an ACCEPT 
statement can be automatically validated by type (alpha or 
numeric) and range of values; data not of the appropriate 
type or value are rejected and must be reentered by the user. 
ACCEPT can also perform branches to other statements based 
on the use of PF keys and on whether displayed data values 
are altered. ACCEPT cannot branch to marked subroutines, as 
INPUT can. The ACCEPT statement is discussed in detail in 
Section 7.5 and in Part II. 


7.2 PRINTER OUTPUT 


Most printers have 132 columns, numbered left to right from 
column 1 through column 132. The columns are divided into seven 
zones; zones begin in columns 1, 19, 37, 55, 73, 91, and 109. All 
zones occupy 18 character positions, except the rightmost zone, 
which is 24 characters wide. 


Data can be directed to the printer by using the PRINT statement 
after a SELECT PRINTER statement is executed. Either literals or 
the current value of any variable or expression can be printed, 
uSing a wide variety of formats. 


The PRINT statement actually moves data to a line buffer for the 
printer. The contents of the line buffer are printed only when an 
implied or explicit move to the next line occurs (e.g., via the SKIP 
clause of a PRINT statement or via a PRINT statement with no 
trailing semicolon) or when data overflows the capacity of the line 
buffer. When the contents of the buffer have been printed, the 
buffer is cleared and restarted at the first position. 


The BASIC program can conclude a print operation by printing the 
contents of the line buffer with or without advancing to the next 
line (line feed). No line feed allows a program to overprint one 
line with another; line feeds are suppressed by ending a PRINT 
statement with a semicolon. See Part II for details. The: program 
can also cause a specified number of blank lines to be fed from the 
printer (with the SKIP clause of the PRINT statement). 


Normally, if the BASIC program outputs more characters than fit 
on the current print line, as many characters as possible are placed 
in the line buffer, the contents of the buffer are printed, and the 
remaining characters are moved to the start of the buffer for 
printing on the next line. This is equivalent to the "wraparound" 
phenomenon in workstation output (see Subsection 7.3.1). 


Wang VS BASIC also provides expanded print capabilities. When a 
printer has been specified in a SELECT statement, double-—width 
letters can be printed on a line-by-line basis. The command PRINT 
HEX(OE) as the first character of a line initiates the expanded 
print, which continues until a carriage return is encountered. The 
maximum number of expanded print characters that will fit on a line 
is 61. The carriage return automatically cancels the expanded print 
option. If multiple lines of expanded print are desired, each line 
must begin with the PRINT HEX (OE) command. 


For details on the use of the PRINT statement, see Part II. 


7.3 WORKSTATION INPUT/OUTPUT 


The workstation display contains 24 rows of 80 characters, for a 
total of 1920 character positions. Each character position in the 
display can be referred to by its row and column number. _ Thus, 
position (1,1) is the first position on the top row; position (24,1) 
is the first position on the bottom row. All the positions in a row 
form a line. The PRINT statement further divides each line into 
zones that begin at columns 1, 19, 37, and 55 (these correspond to 
the zones used in printer output). 


7.3.1 Wraparound 


The entire workstation screen can be thought of as_ one 
sequential record containing 1920 bytes (actually, the record 
contains 1924 bytes, of which the first 4 are control characters 
normally transparent to the user). The order of bytes is from left 
to right within each line, and from each line to the one below. 
Thus, a character position to the right of another position on the 
same line is thought of as being “beyond" the position to its left. 
Similarly, a character position on a physically lower line of the 
screen is beyond a character position on a physically higher line. 


Each line is considered to "wrap around" to the next line: 
column 1 of any line is thought of as directly following column 80 
of the line above it. Thus, if a string of characters is directed 
to a line on which there is not enough space remaining to fit the 
specified characters, as many characters as possible are displayed 
on the current line, and the rest are displayed on the next line. 
However, column 80 of line 24 (the physical end of the screen) does 
not wrap around to column 1 of line 1. 


7.3.2 Scrolling 


If wraparound occurs when the cursor is at the end of the 
screen, or if the cursor is explicitly directed to move down one 
line when already on the bottom line of the screen, all data then 
displayed on the screen is shifted up one line. This makes the 
cursor appear to move down relative to the text on the screen. This 
operation is called an "upward scroll" or "roll-up." Similarly, a 
command to move the cursor up past the top line of the screen 
results in all the text displayed on the screen shifting down one 
line —- a "downward scroll" or "roll-down." 


In a scroll, a new line filled with spaces (ASCII code HEX(20)) 
appears on the screen, and one line leaves the screen. The program 
cannot recover data on the line that leaves the screen. 


7.3.3 Field Attribute Characters (FACs) 


Any position on the screen can contain any 8—bit (1 byte) binary 
code. The codes from HEX(00) to HEX(7F) represent characters that 
can be displayed on the workstation screen. HEX(20) is the "space" 
or "blank" character. HEX(00) also displays as a blank. 


The codes from HEX(80) to HEX(FF) are Field Attribute Characters 
(FACs). FACS occupy character positions, but do not display a 
graphic character. FACs define the start of a field and contain 
information that is applied to all character positions beyond it 
until either another FAC occurs or the end of the line is reached. 
This information governs the following decisions: 


1. Whether the field is displayed bright, dim, blinking, or 
nondisplay (i.e., displayable characters of the field will 
be suppressed). These four options are mutually exclusive. 


2. Whether an underline appears in all character positions in 
that field, or in none. 


3. Whether the field is modifiable by operator input or 
protected. 


4. Whether (a) no restrictions are placed on operator input, 
(b) input lowercase letters are capitalized, or (c) only 
digits 0 through 9, decimal point, and minus sign are 
allowed as input. Note that this affects input only; any 
characters in any field type can be output. This 
information is irrelevant if the field was declared 
"protected" by Option 2. 


Appendix F contains a list of the Field Attribute Characters. 


When BASIC programs are running, the conditions assumed at the 
start of each line are: (1) dim display, (2) not underlined, and 
(3) protected. There is an "assumed" FAC (HEX(8C)) with those 
characteristics to the immediate left of column 1 of each line. 


The programmer can output FACs at any time by specifying the 
correct hexadecimal code in any screen I/O statement. For example, 


300 PRINT HEX(94); 


places on the screen at the current cursor position a FAC that 
causes data displayed to its right to be blinking, with no 
underlining, and protected. 


The INPUT statement places a FAC (of HEX(81)) in the screen 
buffer to the left of the field where input is to occur, thus 
setting that field to "bright, no-line, modifiable, uppercase." 


The ACCEPT statement places a FAC before each input field. This 
FAC will normally specify (1) bright display, (2) not underlined, 
and (3) modifiable. The setting of Option 4 depends on the type of 
item to be entered in that field. If a string is to be entered, the 
setting is "no- restrictions on input" (HEX(80)). If a 
floating-point number is to be entered, the setting is "uppercase 
only" (HEX(81)), to allow input of +, -, ., and E. If an integer is 
to be entered, the setting is "numeric only" (HEX(82)). The 
programmer can override these FAC values with a FAC clause in the 
ACCEPT statement. (See Subsection 7.5.1.) 


Unless the input field is followed immediately by another input 
field, the ACCEPT statement places an additional FAC (HEX(8C)) at 
the end of the field to revert the display to the default settings. 


7.4 THE USING CLAUSE AND FORMAT CONTROL STATEMENTS 


The PRINT statement and a number of file I/O statements (see 
Section 8.4) can use an auxiliary statement to define the format of 
data for output or input. This format-control option is specified 
by including a USING clause, which contains the line number or 
statement label of either a FMT statement or an Image (%) 
statement. For example: 


15600 PRINT USING RADISH, list of expressions 


33200 RADISH: FMT list of format specifications 


67200 ZOutput image 


73600 PRINT USING 67200, list of expressions and/or literals 


Note that the position of the FMT or % statement in the program 
relative to the statement containing the USING clause is 
irrelevant. The FMT and % (Image) statements are nonexecutable 
statements that contain formatting information for an I/O statement 
containing a USING clause. 


7.4.1 The FMT Statement 


A FMT statement consists of the reserved word FMT, followed by a 
list of control specifications, data specifications, and literals. 
Control specifications are clauses that determine the placement of 
data; they specify tab stops, column positions, and numbers of 
spaces or lines to be skipped. Data specifications are clauses that 
determine the type and format of particular data values for input or 
output: alpha or numeric, number of digits to each side of decimal 
point, retention or suppression of leading zeroes, etc. (For the 
general form of the FMT statement and a list of the kinds of control 
and data specifications, see Part II.) For example: 


FMT COL(10), CH(8), XX(2), PIC(4####. ++) 

The control and data specifications in this statement are: 

COL(10) Control specification indicating that the first 
data item begins at the tenth position on the 
workstation or printer line (or, if used for 


file I/O, the tenth byte of the record). 


CH(8) Data specification for an alphanumeric character 
("CHaracter") value 8 characters long. 


XxX(2) Control specification indicating that two spaces 
are to be skipped. 


PIC ( #44+# . $#) Data specification giving an "image" or 


"picture" of a numeric value with four digits to 
the left of the decimal point, two to the right. 
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7.4.2 The Image (%) Statement 


An Image (%) statement consists of the single character "%" 
followed by an image or "picture" of how the output data will look. 
Fields of number signs (#) act as data specifications, which show 
where and how data values will be input or output. Unlike the FMT 
statement, there are no control specifications; the information that 
would be given by control specifications in a FMT statement is given 
in an Image (%) statement by the actual layout of the fields of 
number signs. Special editing characters in these fields indicate 
the placement of signs, decimal points, commas, exponent fields and 
other special characters used with numeric data. Fields that 
describe separate data items must be separated by one or more 
spaces. (For a detailed description of the Image (%) statement, see 
Part II.) For example: 


% ### UNITS @ SH##+#. ## 


This statement has two data specification fields and a literal. 
The first data specification field is three characters long, 
beginning at the fourth character position of the workstation or 
printer line (fourth byte of a record if used for file I/0). This is 
followed by the literal UNITS @ and the second data specification 
field, eight characters long, beginning at the eighteenth character 
position (byte). Either alpha or numeric data is acceptable as 
input or output in either of these data specification fields. 
Numeric data output through the second would appear with two digits 
to the right of the decimal point, and a dollar sign to the left of 
the leftmost digit. 


7.4.3 Use of FMT and Image (%) Statements 


PRINT and file I/O statements with USING clauses can contain a 
list of expressions that are to be produced as output. Starting at 
the beginning of the list, items from the list of the PRINT or file 
I/O statement must correspond with the data specifications in the 
FMT or Image (%) statement. Thus, to print a numeric value followed 
by an alpha value through an FMT statement, the FMI statement must 
contain a numeric data specification followed by an alpha data 
specification. For example: 


1400 PRINT USING JUVENESCENCE, MAGNITUDE, NAME$ 
1500 JUVENESCENCE: FMT PIC(##+H#), CH(16) 


prints the current value of MAGNITUDE using the specification 
PIC(#4HH#), and then prints the current value of NAME$ using the 
specification CH(16). Any attempt to input or output data through 
an FMT or Image (%) statement whose data specifications do not match 
those of the data actually presented results in a data conversion 
error at run time. If the error is caused by a PRINT statement, 
execution halts and an error message is displayed. If caused by a 
file I/O statement, the branch indicated in the data error exit 
clause (see Section 8.6) is taken; if no data error exit was 
specified, execution halts with an appropriate error message. 
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If there are more items in the PRINT or file I/O statement than 
there are data specifications in the FMT or Image (%) statement, the 
FMT or Image (%) statement is reused as many times as necessary to 
accommodate the remaining items in the list of the I/O statement. 
An error message occurs if a PRINT or file I/O statement with a 
non-null argument list is used in conjunction with a FMT or Image 
(%) statement containing no data specifications. In PRINT USING, 
subsequent output occurs on the next line down unless the item in 
the PRINT USING statement that exhausted the FMT or Image (%) 
statement was followed by a semicolon. 


If there are more data specifications in the FMT or Image (%) 
statement than there are items in the PRINT or file I/O statement, 
the remainder of the FMT or Image statement is ignored. The I/0 
Operation ends at the first data specification without a matching 
item from the I/O statement. This situation can also occur when an 
FMI or Image (%) statement is reused, but contains more data 
specifications than there are items remaining in the I/O statement. 


For example, 


1100 %—H#4 XYZ —H#H+. #4 
1400 PRINT USING 1100, E, F, G 


displays the current contents of E using the Image "—-###", then the 
literal "XYZ", and then the current contents of F, using the image 
"Hit ##", Now G remains in the PRINT USING list, but the Image (%) 
statement is exhausted. Therefore, the process begins again. Since 
F and G are separated by a comma instead of a semicolon, subsequent 
display occurs on the next line down. G is printed using the image 
"_###" and XYZ is printed on the same line. Printing stops here, 
since there are no more arguments to use the next data specification. 


7.5 THE ACCEPT STATEMENT 


ACCEPT is the most versatile of the VS workstation I/0 
commands. A single ACCEPT statement displays a formatted screen of 
data at the workstation, which can include literal messages as well 
as the values of numeric and alpha expressions. New values can be 
entered by the user for receivers displayed on the screen. Note 
that ACCEPT processes an entire screen full of data at one time, 
instead of one line at a time, as is done by INPUT. An ACCEPT 
statement consists of the word ACCEPT, followed by a list of items 
to be displayed on the workstation screen. A single ACCEPT 
statement can perform any or all of the following functions, 
depending on the use of various optional clauses: 


1. Display literal messages. 


2. Display current values of variables and alpha receivers in 
an optionally specified format (PIC, CH clauses). 
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3. Control placement of displayed literals and receivers (AT 
clause). 


4. Control display mode of displayed receivers (FAC clause). 
5. Accept modifications to the values of displayed receivers. 


6. Validate modifications to receivers to confirm that they are 
within a specified range of values (RANGE clause). 


7. Accept input from Program Function Keys (KEYS, KEY clauses). 


8. Branch to different places in a program depending upon the 
user's response to the ACCEPT statement (ON and NOALT 
clauses). 


For the general form of the ACCEPT statement, see Part II. The 
following subsections illustrate the use of each of the optional 
clauses by example. 


7.5.1 Screen Formatting 


Fields 


When an ACCEPT statement is executed, the entire screen is 
cleared and a screen is displayed containing items specified in the 
ACCEPT statement. The items that can be displayed are literal 
messages, mumeric variables, and alpha receivers. Unless the 
programmer specifies otherwise, new values can be entered for 
variables and alpha receivers by typing over the displayed values. 
Displayed literals, however, cannot be modified. 


Each item that is displayed occupies a field on the CRT screen. 
A field is a sequence of adjacent character positions on the 
workstation screen that is associated with a particular item in an 
ACCEPT statement. The width of each field is equal to the number of 
characters required to display the item. In the case of literals, 
this is simply the length of the literal itself. For alpha 
receivers, the defined length is used as the field width unless some 
other width is specified with a CH clause. Field width for numeric 
variables is 18 characters unless some other width is specified with 
a PIC clause. 


ACCEPT shows the field that a variable or alpha receiver 
occupies by displaying all blank spaces in the field as 
pseudoblanks. These appear on the screen as solid squares, and are 
shown in the following examples as underscores. For example: 


100 A=99 

200 B$="BOTTLES" 

300 ACCEPT A, B$, "OF BEER ON THE WALL." 
400 PRINT A, B$ 


generates a screen containing the line 
_99 BOTTLES OF BEER ON THE WALL. 


The value of A is displayed in a field 18 characters wide: a 
leading pseudoblank is shown where a minus sign would be displayed 
if the value were negative, followed by the digits 99, followed by 
15 trailing pseudoblanks. Since B$ was not explicitly dimensioned, 
it has a default length of 16 characters. Thus, 9 pseudoblanks are 
shown following BOTTLES. The literal OF BEER ON THE WALL is 
displayed exactly as written, with no pseudoblanks. Note that a 
space is displayed before the beginning of each field. This space 
contains a Field Attribute Character (see Section 7.3.4). 


Positioning Data on the Screen: The AT Clause 


The AT clause can be used to position a field anywhere on the 
screen by specifying the row and column of the screen at which a 
particular field begins. In the example above, the first value was 
displayed starting at the second column of the first row; the first 
column of every row is inaccessible for displaying data, since it 
always contains a FAC. If line 300 was changed to 


300 ACCEPT AT (12, 25), A, BS, AT (13, 25), "BEER ON THE WALL." 


the following would appear in the center of the screen (starting at 
the twenty-fifth column of rows 12 and 13): 


_99 BOTTLES 
OF BEER ON THE WALL. 


If no AT clause is specified for a field, the field is positioned 
according to the default rules specified in Part II. 


Controlling Display Attributes for a Field: The FAC Clause 


In addition to controlling the position of literal and receiver 
fields on the screen, the ACCEPT statement allows the programmer to 
specify the display attributes of a field. The display attributes 
determine whether a field is: dim, bright, blinking, or not 
displayed; modifiable or protected; containing uppercase, numeric, 
or all characters; underlined or not underlined. Display attributes 
are controlled by displaying a Field Attribute Character (a FAC; see 
Subsection 7.3.4) immediately preceding a field. For example, in 
the example above, changing line 300 to 


300 ACCEPT AT (12,25), A, FAC(HEX(91)), BS, AT (13,25), ' 
350 “OF BEER ON THE WALL." 


causes the same message as before to be displayed, except that the BS 
field (containing the string BOTTLES) would be blinking, since 
HEX(91) is the FAC specifying blink, modifiable, uppercase, no line. 


If the display attributes for a particular field are not 
explicitly defined with a FAC clause, the following defaults are 
used: 


Alphanumeric —- bright, modifiable, uppercase, no underline 
(HEX(81)). 

Floating-point - bright, modifiable, uppercase, no underline 
(HEX(81)). 

Integer — bright modifiable, numeric only, no underline 
(HEX(82)). 


Note that FACs cannot be specified for literal fields, which are 
always shown preceded by a FAC of HEX(AC) (dim, protect, all, no 
line). 


Format Images of Displayed Receivers: The PIC and CH Clauses 


It is often useful to be able to display modifiable data fields 
in formats other than the default formats described above. This can 
be done with the PIC clause for numeric fields and with the CH 
clause for alpha fields. Each of these optional clauses appears 
directly after the receiver it modifies in the ACCEPT statement, 
separated from the receiver by a comma. The PIC clause specifies a 
format image for numeric data, and the CH clause specifies a field 
width in characters. For a description of all of the editing 
characters that can be used in a PIC clause, see the discussion of 
this clause under the FMT statement in Part II. For example, if it 
were known that the variable A would never require more than three 
character positions to be displayed, the statement 


300 ACCEPT AT (12,20),A,PIC(###),B$,CH(7), "OF BEER ON THE WALL." 
would display 
_99 BOTTLES OF BEER ON THE WALL. 


on line 12 of the workstation screen. Note that the A and B$ fields 
no longer contain trailing pseudoblanks. 


7.5.2 Data Entry and Validation 


Data Entry 


When an ACCEPT screen is first displayed, the cursor is 
positioned at the first character of the first modifiable field. 
New values for any numeric variables or alpha receivers can be 
entered by typing over the displayed values in the appropriate 
fields, provided that the field has not had a PROTECT FAC placed 
before it. 
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The cursor control keys (the four keys on the workstation marked 
with arrows) move the cursor to different fields on the screen, as 
do the TAB, BACK TAB, and NEW LINE keys. TAB moves the cursor to 
the beginning of the next modifiable field, BACK TAB moves it to the 
beginning of the previous modifiable field, and NEW LINE moves it to 
the beginning of the next modifiable field that is not on the 
current line. All three of these keys move the cursor without 
affecting any of the values displayed on the screen. A field can be 
set to all blanks from the current cursor position to the end of the 
field by pressing the ERASE key. 


Any attempt to type over a nonmodifiable field or to otherwise 
type characters prohibited by the FAC governing a particular field 
causes the workstation alarm (a beep) to sound, and the cursor will 
not move. 


None of the changes made to data on the workstation screen are 
actually transmitted from the workstation to the computer until the 
ENTER key (or a PF key) is pressed, allowing the user to modify data 
repeatedly until this point. When the ENTER key is pressed, the 
data displayed on the screen is transmitted from the workstation to 
the computer; execution then continues either with the next 
statement or with optional ACCEPT clauses. 


Data Validation: The RANGE Clause 


The optional RANGE clause can be used to perform automatic data 
validation to insure that data entered from the workstation falls 
within a specified range of values. A RANGE clause is inserted 
after the name of a receiver in an ACCEPT statement, separated from 
the receiver name by a comma; it applies only to that receiver. For 
numeric data, the range can be specified as being positive 
(RANGE(POS)), negative (RANGE(NEG)), or between the values of two 
expressions evaluated at run time (RANGE(expl, exp2)). For alpha 
receivers, the range can be specified as being between the values of 
two alpha expressions in the ASCII collating sequence 
(RANGE(alpha-expl, alpha-exp2)); see Subsection 5.2.3 for a 
discussion of the ASCII collating sequence. 


When ENTER is pressed during the execution of an ACCEPT 
statement, the value shown on the screen for each modifiable field 
is compared to the corresponding RANGE specification, if one 
exists. If any modifiable field contains a value that falls outside 
that specified, the screen is redisplayed with the first incorrect 
field blinking, and the user must reenter the value. When all 
fields satisfy their RANGE specifications, execution continues. For 
example, 


300 ACCEPT AT (12,15), A, PIC(###), RANGE(50,100), BS, CH(7), ' 
350  RANGE("BARRELS", "KEGS"), "OF BEER ON THE WALL." 


displays 


_99 BOTTLES OF BEER ON THE WALL. 
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If the value in the numeric field is changed to 45, the screen 
is redisplayed with that field ("45") blinking, since 45 is not 
within the specified range. Altering the value to any value between 
50 and 100 causes it to be accepted. Similarly, if BOTTLES is 
changed to LITERS, that field flashes when entered, since LITERS is 
not between BARRELS and KEGS in the collating sequence. CASES, 
however, is accepted. 


7.5.3 PF Key Usage and Program Branching 


The ACCEPT statement allows the program to respond to specified 
Program Function (PF) keys. When a PF key is pressed, its value can 
be assigned to a variable for subsequent testing and branching (or 
for use in a numeric expression), or it can be automatically tested 
by ACCEPT, initiating an immediate branch to another statement (ON 
key clause). This capability is useful for writing interactive 
programs in which the user can select options or issue commands from 
a menu (see Subsection 1.2.2). 


If any of the three PF key clauses are present, they must appear 
after all of the literals, receivers, and modifying clauses. If 
more than one of these three appear, they must appear in the order 
in which they are discussed in the following paragraphs. 


The KEYS Clause 


The KEYS clause specifies which of the 32 PF keys is processed 
by an ACCEPT statement. Pressing any PF key that has not been 
enabled by a KEYS clause causes the workstation alarm to sound, and 
the key is ignored. KEYS must be followed by an alpha-expression in 
parentheses, which is interpreted as a list of one-byte binary 
values corresponding to the numbers of the PF keys to be accepted. 
Such a list can be specified either with the BIN function or with 
the HEX function. In the latter case, the PF key numbers must be 
converted to hexadecimal. 


For example, to enable PF keys 1, 12, and 15, one would write 
either 


KEYS(BIN(1) & BIN(12) & BIN(15)) 
or 
KEYS (HEX(010COF) ) 


Once any valid PF key is pressed, execution of the program continues 
and data on the screen can no longer be modified. 


The KEY Clause 


The KEY clause assigns the value of whatever valid PF key is 
pressed to a numeric variable, which is specified in parentheses 
after the word KEY. For example, if the clause KEY(OPTION) is in an 
ACCEPT statement, and the user presses PF15, the value 15 is 
assigned to the variable OPTION, and execution continues. 
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The ON Key Clause 


The ON key clause enables the program to branch to different 
points depending upon which PF key is pressed. The ON key clause 
can perform either GOTO or GOSUB branches. In either case, the 
branch is taken without reading any changes made to the screen. As 
in the KEYS clause, ON is followed by an alpha expression that is 
treated as a list of l1-byte binary values of PF key numbers. The 
GOTO or GOSUB verb must be followed by a list of line numbers and/or 
statement labels to which branches can be made. MThe position of 
each line number or statement label in this list must correspond to 
the position of its associated PF key in the list of PF key numbers 
following the word ON. Thus, pressing the first PF key listed 
initiates a branch to the first line number or statement label, the 
second PF key to the second line number or label, and so on. For 
example, : 


ON (BIN(1) & BIN(16)) GOTO 100, FINISH 
ON (BIN(5) & BIN(9)) GOSUB CATERPILLAR, BUTTERFLY 


transfers control to line 100 if PFl is pressed, to the statement 
labeled FINISH if PF16 is pressed, and to the appropriate 
subroutines if PF5 or 9 is pressed. 


The ALT and NOALT Clauses 


When data entry to an ACCEPT statement is terminated by ENTER or 
a PF key, the ACCEPT statement can automatically determine if any 
field has been modified. Any keyboard action that is performed on a 
field, even retyping the old data or erasing pseudoblanks, indicates 
that the field has been altered. 


The ALT clause can be used to increase the efficiency and speed 
of screen processing by causing the ACCEPT statement to read, 
validate, and transfer only those fields that were actually modified. 


The NOALT clause is a conditional branch clause that can perform 
either GOTO or a GOSUB branch to a line number or a_ statement 
label. If this clause is included, and none of the displayed fields 
are altered, control passes to the specified line or statement. If 
any fields are altered, only those that have been altered are read, 
validated, and transferred (as with ALT), and execution continues 
without taking the specified branch. For example, 


NOALT GOTO LILLIPUT 
NOALT GOSUB 37200 


ALT and NOALT cannot both appear in a single ACCEPT. In any 


case, this would be redundant, since NOALT performs the function of 
ALT if any fields are modified. 
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7.5.4 Summary of ACCEPT Execution 


1. The screen is generated as described, with the cursor 
positioned at the first modifiable (or numeric-—protected) 
field, if any are present. All fields contain the current 
values of the receivers. 


2. The user can enter new values. When ENTER is keyed, or a PF 
key is pressed, the key is first checked for validity. If 
invalid, the workstation alarm sounds, and the user can 
continue modifying or press another key. 


3. If the key is specified in the ON clause, the specified 
branch is taken without any field reads or verification. 
(The KEY variable, if specified, contains the key number in 
any case.) 


4. Otherwise, all modifiable fields (or only altered fields if 
ALT or NOALT is specified) are read/validated. Numeric 
fields are validated for proper numeric format independently 
of range validation. Although any PIC specification can be 
used, special characters (CR,DB, etc.) are not valid on 
input. 


If any field is invalid, its FAC is set to blinking and the 
user must correct the mistake (and can further change other 
fields). 


Example: 


300 ACCEPT AT (12, 15), A, PIC(###), RANGE(50,100), 

310 FAC(HEX(91)), BS, CH(7), RANGE("BARRELS", "KEGS"), 
320 "OF BEER ON THE WALL.", 

330 KEYS(BIN(O) & BIN(1) & BIN(16)), KEY(OPTION), 

340 ON (BIN(1) & BIN(16)) GOTO START, FINISH, 

350 #NOALT GOSUB 1700 


7.6 THE DISPLAY STATEMENT 


DISPLAY, like ACCEPT, clears the workstation screen and displays 
an entire formatted screen at one time. Unlike ACCEPT, however, 
DISPLAY does not accept any input either of data values or PF keys. 


DISPLAY can position data with the AT clause, and can specify 
formats of displayed numeric and alpha data with the PIC and CH 
clauses. These three clauses all operate as in ACCEPT. DISPLAY can 
also position data with the COL clause, which has the form COL(n), 
where n is an integer. COL(n) specifies that the next data item is 
to be displayed starting at the n-th column of whichever row the 
cursor is currently on. 


For further details on DISPLAY, see the entries on DISPLAY and 
ACCEPT in Part II. 


7.7 WORKSTATION PROGRAMMING CONSIDERATIONS 


When programming output to the VS workstation, it is important 
to keep in mind that the workstation is capable of producing output 
much more quickly than a human user can read. Incautious use of 
statements that clear the workstation screen can lead to output 
being erased from the screen before the user can read it. For 
example, if two DISPLAY statements follow one another with few or no 
intervening statements, the data displayed by the first DISPLAY may 
be on the screen for only a fraction of a second before the second 
DISPLAY statement erases it. (The actual duration of the screen 
display depends on many variables at execution time, including how 
many other users are logged onto the VS, how much main memory is 
available to each user, etc.) 


There are several ways to avoid this problem. The SELECT P[{d] 
statement can be used to make the program pause for d/10 seconds 
after each DISPLAY or PRINT to the workstation. The pause interval 
remains the same until another SELECT P[d] is_ encountered, 
regardless of the amount of data displayed (and therefore regardless 
of the time required to read the screen). 


The STOP statement can be used after a DISPLAY or PRINT 
statement to halt execution while the user reads aé_e screen. 
Execution is resumed when the user presses the ENTER key or a legal 
PF key (one which corresponds to a marked subroutine; see Subsection 
6.4.3). The STOP statement displays the word STOP and an optional 
literal when it is executed. 


Since all of the functions of the DISPLAY statement (except 
sounding the workstation alarm) can be performed by the ACCEPT 
statement, ACCEPT statements can be used to display information 
without performing any meaningful input. To allow the user time to 
read a long message on the screen, one can display the message as a 
series of literals and/or expressions with the ACCEPT statement, and 
enable only the ENTER key (PFO, specified with a KEYS(BIN(0)) 
clause) for input. When the ACCEPT statement is executed, the 
desired message is displayed on the screen, and remains there until 
the user presses the ENTER key. 


CHAPTER 8 
FILE INPUT/OUTPUT 


8.1 INTRODUCTION 


Programs written in VS BASIC can retrieve and store data in files 
located on magnetic disk or tape. The first part of this chapter 
(Section 8.2) provides general background information on the types of 
files supported on the VS, and their attributes and structures. Only 
that information required for the use of the BASIC file input/output 
facilities is included. Programmers requiring further detail on the 
organization of VS files and on the operation of the Data Management 
System should consult the VS Operating System Services. The rest of 
this chapter describes the specific features of VS BASIC that 
facilitate file I/O operations, including detailed examples of the 
use of the most frequently used file I/O statements. 


8.2 FILES 


A file is a collection of data stored on either magnetic disk or 
tape, and identified by a file name. Files are made up of records. 
A record is the unit of all file input/output operations, and 
consists of a continuous series of bytes of data that are processed 
together. In general, a record corresponds to whatever unit of data 
is logically most convenient to .process at onetime. For example, 
in an inventory control program, a single record might consist of a 
part number, the quantity in stock, quantity on order, order date, 
price, and so on. An inventory file for 100 different parts would 
thus contain 100 records. Ina file of text (for example, a BASIC 
source file), each record would correspond to a line of text as 
shown on the workstation or printer. 


8.2.1 File Types 


The VS supports four different types of disk files (consecutive, 
indexed, print, and WP files) that differ in their internal 
organization and use. The details of internal file organization for 
consecutive, indexed, and print files are transparent to the BASIC 
programmer, since these are all managed and maintained by the Data 
Management System (DMS; see Subsection 1.3.1). The Document Access 
Subroutines allow a BASIC program to access VS word processing 
documents. This subsection contains a general discussion of the 
four file types. Section 8.3 describes the BASIC statements that 
control file selection and use. 


Consecutive Files 


A consecutive file contains records that physically follow one 
another within a block (a block is 2048 (2K) contiguous bytes of 
storage space) in the same order in which they were written. The 
information in a record does not in any way influence its position 
within the file. The position of a record relative to other records 
in a file therefore depends only on when it was written relative to 
other records. 


Records in a consecutive file can be read either sequentially or 
by position. In sequential reading, the user program in effect 
instructs the Data Management System to get the next record, whereas 
reading by position is equivalent to instructing DMS to retrieve the 
n-th record. 


Indexed Files 


An indexed file is a disk file that contains records in a logical 
sequence that is not necessarily the same as the order in which the 
records were written (as would be true of a consecutive file). The 
logical sequence of records in an indexed file is determined by the 
value of the primary key of each record. A primary key is a 
designated portion of a record (the eighth through the twelfth bytes 
of each record, for example) that is used to sort the records into a 
particular ordered sequence. Each record in an indexed file must 
have a unique primary key. 


Indexed files can also have alternate keys. Like the primary 
key, an alternate key is a section (or field) of a data record of 
some designated position and length. One file can use up to 16 
alternate keys, numbered 1 to 16. Every record in an indexed file 
has an alternate index mask associated with it; a mask is a two-byte 
(16-bit) field that specifies which alternate keys can access that 
record. 


Indexed files enable a program to access particular records 
according to primary or alternate key value. Records can be read 
from an indexed file sequentially or by key. In sequential reading, 
the program instructs DMS to get the next record in ascending 
primary key sequence. Reading by key, on the other hand, instructs 
DMS to get the record with a key equal to x. 


Indexed files are organized into data blocks and index blocks (a 
block is 2048 (2K) contiguous bytes of storage space). Data blocks 
contain the actual data records, in primary key sequence, within each 
block. The index blocks contain a list of primary key values of 
records in the file, with a corresponding list of pointers that 
indicate in which block a record with a particular key can be found. 
Files with alternate keys have a separate numbered alternate index 
for each defined alternate key field. Each alternate index contains 
entries only for those records whose alternate index masks specify 
that they are accessible by that key. 


The first time an indexed file is opened for output (i.e., when 
it is created), any records written to it must be written in key 
sequence. Later additions to the file can be made in any order. 
DMS inserts the data records and index entries into their respective 
blocks at the appropriate points. When either an index block or a 
data block becomes full, it is split; the contents of half of the 
block are moved to an empty block. The result is two half-empty 
blocks, instead of one full block. New insertions can then be made 
in the two blocks until one or both are full, and the splitting 
process takes place again. 


Print Files 


A print file is a disk file used to store records that are to be 
output by a printer. The records in a print file, like those in a 
consecutive file, always appear in the order in which they were 
written. In addition to the data records, print files contain 
printer control bytes that hold information affecting the physical 
appearance of print on a page (line-feed codes, page breaks, etc.). 
BASIC programs can write print files, but cannot read them. Print 
files are generally only read by printer Input/Output Processors 
(IOPs) and certain System Utility programs (e.g., DISPLAY). 


WP Files 


A WP file is a disk file that is organized for access by VS Word 
Processing. All WP files are consecutive files with fixed-length, 
noncompressed, 256-byte records. WP files include VS_ word 
processing documents and OIS files that reside on the VS for use 
within VS Word Processing. OIS files can only be read by VS Word 
Processing or the COPYOIS utility; however, BASIC programs can 
access VS word processing documents. 


Because WP files do not conform to standard DMS file structures, 
a BASIC program cannot directly manipulate VS word processing 
documents through BASIC I/O statements. The VS Document Access 
Subroutines, described in the VS Programmer's Guide to VS/IIS, are 
provided with the VS Word Processing software to allow program 
access to VS word processing documents in the data processing 
environment. The Document Access Subroutines allow a BASIC program 
to directly open, read, write, search, and print VS word processing 
documents. Because WP files do not use the standard BASIC I/0 
statements, subsequent discussions of I/O methods in this manual 
ignore WP files. 


8.2.2 Record Types: Length and Compression 
Record Length 


Files can contain records that are all of the same length 
(fixed-length records) or of differing lengths (variable-length 
records). The record length is specified in the file label of files 
with fixed-length records. In files with variable-length records, 
the length of each record is specified by a length count at the 
beginning of each record (this is maintained by DMS and is thus 
transparent to the user). 
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Record Compression 


Variable-length records can also be compressed. If record 
compression is specified for a file, characters that are repeated 
three or more times consecutively are stored on the disk only once, 
preceded by a_ repetition factor. Compression is performed 
automatically by DMS when information is moved to the _ disk; 
compressed records are decompressed when the reverse transfer is 
performed. The entire compression/decompression process is 
completely transparent to user programs. Record compression can 
often save substantial amounts of disk space. 


8.3 USE OF FILES BY BASIC PROGRAMS 


All transfers of data between user programs and files, except WP 
files, are processed by the Data Management System. The user 
program communicates with DMS about the files to be used through 
User File Blocks (UFBs). A UFB contains information about fixed 
characteristics of the file it describes: whether it is a 
consecutive, indexed, or print file; the record type (fixed- or 
variable-length, compressed or not); record length; and various 
other factors. When a BASIC program is compiled, one UFB must be 
created for each file of particular characteristics to be used by 
the program. These characteristics are all specified in a SELECT 
statement, which also assigns a file-number to a UFB. Note that 
since the UFB is part of the object program, a SELECT statement has 
its effect (creation of a UFB) at compile time. 


In addition to the fixed characteristics of a file specified 
with SELECT, there are factors relating to the way in which a file 
is to be used that are specified at run time and that may change 
during the execution of a program. These include the file's name, 
whether it is to be used for input or output, and how much space is 
allocated for it if it is a new file. These run-time specifications 
are made with the OPEN statement. The OPEN statement initiates a 
connection between the user program and a specific file through a 
particular UFB by associating the name of the file with the 
file-number of the UFB. This connection is severed by the CLOSE 
statement. I/O operations can be performed with a file only if it 
is open. The characteristics (file type, record type and length, 
and so on) of a file named in an OPEN statement must match those 
specified in the SELECT statement for the file-number if the file 
already exists. If the file is being created, it is created with 
the characteristics described by the SELECT statement. 
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Only one file can be opened on a particular file number at a 
time. Thus, a program must contain one UFB, and therefore one 
SELECT statement, for each file with a_ particular set _ of 
characteristics to be open at one time. For example, a program 
might use one consecutive file, one indexed file, and one printer 
file. In this case, it must have three SELECT statements, one to 
create each of the three different UFBs needed. Another program 
might use three consecutive files, each with fixed-length, 80-byte 
records. If no more than one of these files is open at one time, 
then the program needs only one SELECT statement. All three files 
can use the same UFB, since they will be open at different times. 


8.3.1 The SELECT Statement 


The SELECT statement is made up of a series of clauses, some of 
which are optional, that describe the characteristics of the file(s) 
that can be associated with a particular UFB. For the general form 
of the SELECT statement, see Part II. 


The elements of the SELECT statement indicate the following: 


File—number -—- Number sign (#) followed by an integer from 1 to 
64 (inclusive). This file number is used in all other I/0 
statements to refer to the file described by this SELECT. 
statement. Must be specified for each UFB to be created. 


Prname —-- A literal string consisting of 1 to 8 alphabetic or 
numeric characters. Must be specified for each UFB created. 
The prname is not the filename. 


VAR[C] -- Specifies that records are variable length (optionally 
compressed). If not specified, records are fixed length, with 
length specified by the RECSIZE clause. Cannot be specified for 
PRINTER files; optional for all other types. 


CONSEC, INDEXED, PRINTER, TAPE -- Specifies file type. These 
are mutually exclusive choices; one of the four types must be 
specified. Note that a TAPE file is always consecutive in 
form. The word CONSEC, however, always indicates a consecutive 


disk file. 
RECSIZE=intl -- Record length, in bytes, for files with 
fixed-length records. Maximum record length for files with 


variable-length records. Must be specified for every file, 
regardless of type. See SELECT entry in Part II for record 
length limits for each file type. 


KEYPOS=int2 -- Position (starting from byte number 1) of first 
byte of primary key in records of an indexed file. Must be 
specified for an indexed file. 


KEYLEN=int3 -- Length (in bytes) of primary key in records of an 
indexed file. Must be specified for an indexed file. 


ALT[ERNATE] KEY int4, KEYPOS=int5, KEYLEN=int6 -- Number, 


position, and length of an alternate key in the records of an 
indexed file. Optional for an indexed file. Up to 16 alternate 
keys can be specified; each must be identified by a unique key 
number (int4). ALT and ALTERNATE are equivalent forms. 


DUP -- Indicates that duplicate key values are allowed for the 
alternate key specified in the preceding clause. For indexed 
files only. If not specified for an alternate key, any 


duplicate value found for that alternate key will cause the EOD 
exit to be taken. 


IL, NL, AL -— Specifies the tape label type for TAPE files 
only. IL = IBM-type label, NL = no label, AL = ANSI standard 
label. 

BLKSIZE -- Specifies the size, in bytes, of the blocks into 


which TAPE files are divided. 


IOERR -- Specifies a GOTO or GOSUB branch to be taken if an I/O 
error occurs on the file that is opened with the file number 
specified in the SELECT statement (see Subsection 8.3.2). 
Optional for all file types. 


EOD -- Specifies a GOTO or GOSUB branch to be taken if an 
end-of-—data condition, invalid key or duplicate key is found in 
a file while performing an I/O operation that does not have an 
EOD exit of its own. Cannot be specified for PRINTER files; 
optional for all others (see also Section 8.6). 


NOTE 


The prname (parameter reference name) specified in the 
SELECT statement is not a file name. The actual name of 
the file to be used is specified in the OPEN statement. 
The prname is used by DMS to refer to a file at run time 
in requests for information (called GETPARMS) displayed 


on the workstation screen. Such requests appear when 
DMS requires information not specified (or incorrectly 
specified) in the program. GETPARMs are discussed more 
fully in Subsection 8.3.2. 


Note that one SELECT statement must be written for every UFB to 
be used by a program. All SELECT statements must appear in a 
program before any OPEN or file I/O statements. 


File numbers need not be selected consecutively. No file number 
can be used in more than one SELECT statement. 
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8.3.2 The OPEN and CLOSE Statements 


The OPEN statement enables input or output between a BASIC 
program and a file, and associates the file name with the 
file-number of a particular User File Block that has already been 
created by a SELECT statement. In all subsequent file I/0 
statements, the file is referenced by the file-number in the OPEN 
statement. 


The CLOSE statement is used to terminate the connection between 
a file and a numbered User File Block. If a file is open through a 
particular UFB, no other file can be opened through that UFB until 
the first file is closed. The format of the CLOSE statement is: 
CLOSE #f£1le-expression. 


The OPEN statement can specify the name of the file or the user 
can be prompted for it when the OPEN is executed. In the latter 
case, a GETPARM is issued. A GETPARM is a request issued by the 
Data Management System for information needed to perform certain 
operations. When a program is being run directly from a 
workstation, a GETPARM displays a screen specifying what information 
is needed. After the user types this information into the 
appropriate fields on the screen and presses the ENTER key, 
execution continues. If the program is being run from a procedure, 
the procedure is first prompted for the information. The GETPARM 
screen is displayed only if the procedure does not supply all of the 
necessary information, or if some of the information is in error 


(see the VS Procedure Language Reference for a discussion of 


procedures). 


If the file, library, and volume names are specified in the OPEN 
statement and do not need to be changed, the GETPARM prompt can be 
suppressed by specifying NOGETPARM in the OPEN statement. The 
prompt screen can be suppressed by NODISPLAY. This should be used 
only if the correct file, library, and volume names have been 
specified in this or an earlier OPEN statement or in a procedure 
running the program, or if SET defaults are in use (see the 
VS Procedure Language Reference for a discussion of procedures and 
SET defaults). The difference between NOGETPARM and NODISPLAY is 
that the former should be used only if the file, library, and volume 
names are specified in the current OPEN statement. NODISPLAY can be 
used if these specifications are omitted from the statement, as long 
as they can be obtained elsewhere (from an earlier OPEN statement, 
procedure, or SET defaults). 


Even if the file, library, and volume names are specified in the 
OPEN statement, the GETPARM screen is displayed if neither NOGETPARM 
nor NODISPLAY is present. In this case, the user can press ENTER, 
which causes the file specified in the OPEN statement to be used. 
The user can also alter the displayed file, library, and volume 
names. See Part II for the general format of the OPEN statement. 


The elements in the OPEN statement indicate the following: 


NOGETPARM -— Suppresses the issuing of a GETPARM for the file, 
library, and volume names. Should be used only if these are 
specified in the OPEN- statement. Optional and mutually 
exclusive with NODISPLAY. 


NODISPLAY -- Suppresses display of a GETPARM screen for file, 
library, and volume names. An "invisible" GETPARM is issued to 
the controlling procedure if one exists or else the required 
information is obtained from this or an earlier OPEN or from the 
SET defaults. Optional and mutually exclusive with NOGETPARM. 


File-exp -- Specifies a numeric expression that is evaluated to 
obtain the file-number by which this file will be referenced by 
all file I/O statements. 


INPUT -- Opens an existing file for input. The program is then 
able to read from the file, but not to modify it. Mutually 
exclusive with IO, OUTPUT, EXTEND, and SHARED. (Does not apply 
to print files.) See Subsection 8.3.3. 


IQ -— Opens an existing file for input and output. The program 
is then able to read and modify the contents of the file. For 
an indexed file, IO mode allows the addition of new records 
(like EXTEND for consecutive files). A consecutive file with 
fixed-length records can do REWRITEs in IO mode, but cannot 
create new records. Mutually exclusive with INPUT, OUTPUT, 
EXTEND, and SHARED. (Does not apply to printer or tape files.) 


See Subsection 8.3.3. 


OUTPUT -- Specifies that a new file is to be created and opened 
for output, in which case records can be written out to the 
file, but cannot be read from that file. If the file existed 
prior to the OPEN, the user is asked to either delete the old 
file or specify a new name. Printer files can only be opened in 
this mode. Mutually exclusive with INPUT, I0, EXTEND, and 
SHARED. See Subsection 8.3.3. 


EXTEND -— Opens an existing consecutive file for extension. The 
program is then able to write to the file, but not to read from 
it. The first record written is stored directly following the 
last record already in the file. Mutually exclusive with INPUT, 
IO, OUTPUT, and SHARED. (Does not apply to printer files.) See 
Subsection 8.3.3. 


SHARED -- Opens an existing file in shared mode. This mode is 
Similar to IO mode, but allows simultaneous access to the file 
by other VS users. Mutually exclusive with INPUT, I0, OUTPUT, 
and EXTEND. (SHARED mode is supported only for indexed files 
and for a special type of consecutive file called a "log 
file.") See Subsection 8.3.3. 
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SPACE=expl -- Specifies the approximate number of records (exp1) 
to be put in the new file for OUTPUT mode files. If SPACE is 
omitted, a GETPARM is displayed to request the required space 
information. For non-OUTPUT mode files, if expl is a numeric 
variable, it is assigned the number of records in the file when 
the file is opened. 


DPACK=exp2, IPACK=exp3 -- Specifies the percentage packing 


densities of data and index blocks, respectively, for new 
(OUTPUT mode) indexed files_ only. The packing density 
determines what percentage of each data and index block is 
filled with data records and index entries. This affects the 
efficiency of disk space use and the number of records that can 
be inserted into a file before DMS must reorganize a file by 
splitting data and/or index blocks (see the discussion of 
indexed files in Subsection 8.2.2). For most efficient use of 
disk space, files that will never have additional records 
inserted should have DPACK and IPACK set equal to 100. Files 
that will have records inserted should set DPACK and IPACK to 
values less than 100. 


FILE=alpha-expl, LIBRARY=alpha-exp2, VOLUME=a lpha—exp3 -— 


Specifies the file, library, and volume names of the file to be 
opened on the indicated file-number. These will be requested in 
a GETPARM, whether or not they are named explicitly, unless 
NOGETPARM or NODISPLAY has been specified. 


FILESEQ = exp 1 -—- Specifies the file sequence number. This is 
to be used only for tape files to position the Read/Write head 
at the start of the correct file number for tape files. 


8.3.3 File I/O Modes 
VS BASIC supports the following I/O modes. 
INPUT —- Files opened for INPUT can be accessed only through the 
READ statement and, for consecutive files, the SKIP statement. 


The READ statement reads consecutive files from tape and 
consecutive or indexed files from the disk. 


IQ -- Files opened for IO can be accessed through the READ 
statement. If the READ statement specifies the HOLD option, the 
record read can be subsequently modified using the REWRITE 
statement (or, for indexed files, either the WRITE, REWRITE, or 
DELETE statements). As with INPUT, the SKIP statement is 
available for consecutive files. 


OUTPUT/EXTEND --— Files opened for OUTPUT or EXTEND can be 
accessed with the WRITE statement only. EXTEND mode is 
supported only for consecutive disk files. 


SHARED -— SHARED mode disk I/O is supported only for indexed 
files and special log files. The file can be accessed with the 
READ, WRITE, REWRITE, and DELETE statements. Moreover, when a 
program opens a file SHARED, the HOLD option is available in the 
READ statement. This prevents other users from attempting to 
modify or delete the held record until the user has modified or 
deleted it, has begun processing another record, or has closed 
the file. When the second I/O operation is completed, the HOLD 
is released, and other users can again access that record. If 
the first user modified or deleted the record, that action takes 
effect before other users can access the record. A program can 
put a HOLD on only one record at a time. 


8.3.4 File I/O Buffering and the Record Area 


Associated with each open file is a data buffer, maintained by 
DMS, that serves as an intermediate storage location for data 
transferred between BASIC variables and the disk or tape. The size 
of the buffer is normally one block, which is equal to 2048 (2K) 
bytes. The programmer can specify a larger buffer size with the 
BLOCKS clause of the OPEN statement. 


In addition to the DMS buffer, there is another intermediate 
storage area associated with each User File Block, called the record 
area. The size of the record area is equal to the RECSIZE specified 
in the SELECT statement for that file—-number. 


All data transferred between programs and files must pass 
through both the DMS buffer and the record area for that file. 
Transfers between program data (receivers and expressions) and the 
record area, and between the record area and the DMS buffer, are 
always done one record at a time. Transfers between the DMS buffer 
and the file are always performed n blocks at a time, where n equals 
the size of the DMS buffer specified in the BLOCKS clause of the 
OPEN statement (if BLOCKS is omitted, n=1). Figure 8-1 diagrams the 


data transfer. 


program data < 
(1 record ) (1 record ) (n blocks 


(at a time; ) at a time; ) (at a time; 
(controlled by) (controlled by) (controlled by) 
(BASIC program) (BASIC program) (DMS ) 


Figure 8-1. The Data Transfer Path 


The READ and WRITE statements, depending on which forms are 
used, cause data transfer either between the buffer and the record 
area, or between the buffer and program data, through the record 
area. The GET and PUT statements are used to control transfer of 
data between program data and the record area alone. These four 
statements are all discussed more fully in Section 8.4. 
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To illustrate the relation between file-to-buffer data transfer 
and buffer-to-program data transfer, consider a program. that 
processes data from a consecutive file with fixed-length, 80-byte 
records. If a 1-block buffer is used, reading the first record from 
the file loads the first block of the file into the data buffer. 
This 2K block contains 25 80-byte records (plus 48 unused bytes; 
records never span a block). Any subsequent READ or WRITE statement 
that accesses any of the first 25 records of the file actually 
causes data transfer only between program data and the buffer area, 
through the record area. Since all of the first 25 records are 
already in the DMS buffer (which is in main memory), there is no 
need to perform a time-consuming disk or tape I/O operation for 
every record read or written. 


The first time a READ or WRITE occurs that involves a record 
outside of the first block, DMS checks to see if the contents of the 
buffer were modified (by a WRITE or REWRITE). If so, the contents 
of the buffer are rewritten to the disk or tape, replacing the 
original block on the storage device. The block containing the next 
desired record is then read into the buffer from the disk or tape. 
If the contents of the buffer were not modified, the next desired 
block is simply read into the buffer, overwriting its previous 
contents. 


If the programmer sets BLOCKS=2 (or more) in an OPEN statement, 
data will be transferred two (or more) blocks at a time, instead of 
one at a time. This decreases the frequency of calls to DMS to 
perform time-consuming data transfers between main memory and a 
peripheral storage device, but increases the amount of storage space 
used. 


The optimal choice of buffer size in any particular case depends 
on several factors. The frequency of DMS-—processed disk or tape I/O 
operations depends on record size and on the distribution of records 
to be accessed through the file, as well as on buffer size. There 
is also a trade-off between frequency of I/O operations (decreases 
with increasing buffer size) and program memory requirements 
(increase with increasing buffer size). 


The only time a BASIC programmer must consider the DMS buffer is 
when using the optional BLOCKS clause of the OPEN statement. 
Otherwise, the operation and existence of the DMS buffer are 
completely transparent to the BASIC user. Therefore, subsequent 
discussions of file I/O generally refer to data transfers between 
files and record areas, ignoring the intervening DMS buffer. 


8.4 THE FILE I/O STATEMENTS 


Transfer of data between BASIC programs and files is performed 
by five statements: READ, GET, WRITE, PUT, and REWRITE. Records in 
consecutive files can be read selectively by position in the file by 
using the SKIP statement before a READ. The DELETE statement can be 
used to remove selected records from an indexed file. READ, WRITE, 
REWRITE, SKIP, and DELETE operations can be performed on a file only 
while it is open (i.e., after an OPEN statement is executed for that 
file, and before a CLOSE). This section describes the way in which 
data are transferred between the file and the record area, and 
between the record area and program data. For the general forms and 
full discussions of the various optional clauses and modes of use of 
these statements, see the appropriate entries in Part II. 


8.4.1 The READ Statement 


The READ statement causes one record to be read from _ the 
specified file into the record area for that file. READ can be used 
with or without a list of receivers. If a list of receivers is 
included in the READ statement, values are extracted one by one from 
the record area and assigned to the receivers, left to right. If 
USING is specified, the values are assigned according to the formats 
specified in the referenced FMT or Image (%) statement (see Section 
7.4 and the FMT and Image (%) entries in Part II). Otherwise, 
values are assumed to be in-internal format (see below). If no list 
of receivers is present, one record is simply read from the file to 
the record area, and no assignments are performed. Once in the 
record area, a record is available to the GET, WRITE, and REWRITE 
statements. 


If the file being read is consecutive, the RECORDS=n clause can 
be used to specify that the n-th record of the file is to be read. 
If a READ statement on a consecutive file does not have the 
RECORDS=n clause, the next sequential record is read. For indexed 
files, the KEY clause can be used to read a record with a primary or 
alternate key equal to a particular value. See Part II of this 
manual for further details on the READ statement. 


8.4.2 The GET Statement 


The GET statement causes values to be extracted from the record 
area and assigned to one or more receivers. Values are extracted 
from the record area and assigned according to the format in the FMT 
or Image (%) statement (see Section 7.4 and the FMT and Image (%) 
entries in Part II) referenced with the USING clause, if one is 
present. If USING is not specified, values are assigned according 
to the conventions of BASIC's internal format. GET is generally 
used to assign values to receivers after a record has been read from 
a file by a READ statement without a receiver list. If a PUT, 
WRITE, or REWRITE statement was executed more recently than the last 
READ, however, the record area contains whatever record was left 
there by the most recent of these statements. See Part II for 
further details. 
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8.4.3 The WRITE Statement 


The WRITE statement causes one data record to be written from 
the record area to the disk file. WRITE can be used with or without 
a list of expressions. If a list of expressions is included in the 
WRITE statement, their values are first packed into the record 
area. Note that an expression in a WRITE statement cannot contain a 
concatenation operation. If USING is specified, the values are 
packed into the record area according to the format in the 
referenced FMI or Image (%) statement (see Section 7.4 and the FMT 
and Image (%) entries in Part II). If USING is not specified, the 
values are packed into the record area according to the conventions 
of BASIC's internal format. The contents of the record area are 
then written to the specified file. 


If the WRITE statement contains no list of arguments, the 
current contents of the record area are written to the file. 
Generally, this form of the WRITE statement would be used after data 
had been written into the record area by a PUT statement. If a 
READ, WRITE, or REWRITE statement was executed more recently than 
the last PUT, however, the record area contains whatever was left 
there by the most recent of these statements. 


Records written to consecutive files (in OUTPUT, SHARED, or 
EXTEND mode, as specified in the OPEN statement) are added to the 
end of the file. Records written to indexed files (in IO mode) are 
inserted into the file at the appropriate point as determined by 
their primary key values. See Part II for further details. 


8.4.4 The PUT Statement 


The PUT statement causes the values of one or more expressions 
to be packed into the record area of the specified file. If USING 
is specified, the values are packed into the record area according 
to the format in the referenced FMT or Image (%) statement (see 
Section 7.4 and the FMT and Image (%) entries in Part II). If USING 
is not specified, the values are packed into the record area 
according to the conventions of BASIC's internal format. PUT is 
generally used prior to a WRITE statement with no argument list. 


8.4.5 The REWRITE Statement 


REWRITE is like WRITE except that the record that is written to 
the file overwrites the last record read with a HOLD option, instead 
of being written to the end of a file. For a description of the 
HOLD option, see the entry under READ in Part II. REWRITE cannot be 
performed on consecutive files with variable-length records. Direct 
concatenation operations within the REWRITE statement are illegal. 


8.4.6 Summary of Data Flow Controlled by File I/O Statements 


Figure 8-2 illustrates the transfer of data for the READ, GET, 
WRITE, REWRITE, and PUT statements. 


Program Variables ) 
or Expressions (Buffer) 


READ 


GET 


(RE)WRITE 


PUT 


Figure 8-2. Statement-—Dependent Data Transfer Paths 


8.4.7 Data Representation in File I/O 


In using file I/O statements, it is important to keep in mind 
that BASIC represents numeric data in an internal format that bears 
no simple relation to the sequences of ASCII character codes used to 
represent those same data in workstation or printer I/O. Unless 
file I/O is explicitly formatted with the USING clause and Image (%) 
or FMT statements, all file I/O is performed in this internal 
format. While this is suitable for data files that are to be read 
only by other programs, it should not be used for files to be 
directly examined by users, such as report or other text files. Any 
attempt to display or print numeric data from a file in internal 
format produces meaningless strings of characters on the workstation 
or printer. 


Data values packed into records in internal format take up the 
following amounts of space: 


Floating-point -- 8 bytes 
Integer -- 4 bytes 
Alphanumeric -—-— defined length 


If any format conversions are done (i.e., if USING is specified 
in any file I/O statement), they are performed as data are 
transferred between the record area and variables or expressions in 
the program. Data should always be read from a file in the same 
format in which they were written in order to be _ properly 
interpreted by a BASIC program. 


For a discussion of the FMI and Image (%) statements, see 
Section 7.4 and the FMT and Image (%) statement entries in Part II. 


8-14 


8.5 INTRINSIC FILE I/O FUNCTIONS 


Four functions can be used in expressions to retrieve 
information concerning file I/O operations: FS, KEY, MASK, and SIZE. 


8.5.1 FS (File—Expression) 


The FS function returns the file status for the most recent I/O 
operation on the specified file, as an alpha value two characters 
long. FS can assume any of the following values: 


CONSEC, TAPE, and PRINTER file I/O 


'00' Successful I/O operation 

'10' End—of-file encountered 

er Invalid record number 

'30' Hardware error 

'34' No more room in the file 

'95' Invalid function or function sequence 
“9T" Invalid record length 


INDEXED file I/O 


'00' Successful I/O operation 

'10' End-of-file encountered 

0 Key out of sequence (WRITE statement in OUTPUT mode only) 

22 Duplicate key 

bean No record found matching specified key 

"24! Supplied key exceeds any key in the file (INPUT, I0, or 
SHARED mode) 

'34' No more room in the file (OUTPUT or IO mode) 

'30' Hardware error 

"95" Invalid function or function sequence 

'97* Invalid record length 


8.5.2 KEY (File-Expression [,exp]) 


The KEY function returns the value of a key field from the 
specified file's record area. The file-expression given as_ the 
argument of the KEY function must refer to an INDEXED file. The 
optional second expression is a key number specifying which key 
field is desired. If it is omitted or set equal to zero, the 
primary key is returned. Otherwise, the specified alternate key (as 
defined in the SELECT statement) is returned. The KEY function is 
typically read immediately following a READ statement (i.e., without 
an intervening WRITE statement). The KEY function returns an alpha 
value whose length is equal to the value of the KEYLEN parameter in 
the SELECT statement for that file. 


The KEY function can be used as a receiver in order to write 
into the "key" field in the data buffer. For example: 


3900 LET KEY(#3)="NYC" 


KEY is typically used .in this way immediately preceding a READ, 
WRITE or REWRITE statement. The use of arguments in the WRITE, 
REWRITE, and PUT statements causes data to be loaded into the data 
buffer. Depending on the size of the argument list and the position 
of the key field, loading the data buffer through arguments to 
WRITE, REWRITE, or PUT can overwrite the key written into the data 
buffer by the "LET KEY(#n)=" construction. 


8.5.3 MASK (File-Expression) 


The MASK function returns the alternate key access mask for the 
last record read from the alternate indexed file specified. The 
result is a 2-byte alpha HEX value whose component bits (left to 
right) correspond to the record's available alternate keys (1 
through 16). Bits that are "on" (binary 1) specify that the record 
can-be read by those alternate key paths. The bit values can be 
determined by printing, in hexadecimal, the result of the MASK 
function. For example, if the program fragment 


300 READ #1, PLEXIPPUS$ 
400 DIM A$2 

500 A$ = MASK(#1) 

600 PRINT HEXOF(A$) 


were to read a record accessible by alternate keys 1, 3, 5, and 7, 
line 600 would print (or display) 


AAOO 


This represents the binary string 1010101000000000, indicating that 
the first, third, fifth, and seventh alternate keys are used in this 
record. 


The MASK function can also be used as a receiver to set the 
alternate key access mask for a record that is to be written (or 
rewritten). For example, 


2300 MASK(#DESTINATION) = 6400 
causes the next record written to the specified indexed file to be 
accessible by alternate keys 2, 4, and 6 (6400 hex = 0101010000000000 


binary). All records written to this file have the same alternate 
key access mask until another mask value is assigned in this way. 


8.5.4 SIZE (File—Expression) 


The SIZE function returns (as an integer) the size in characters 
of the record most recently read from the specified file. 
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8.6 ERROR RECOVERY 


The situations under which an Input/Output instruction cannot be 
successfully completed fall into four categories: 


1. Errors handled by the VS Data Management System -- There is 
an error or omission in the specification of a file, 


library, or volume name: the file was not found, the volume 
is not mounted, a name was omitted, and so on. 


2. EOD errors —-— There are no more data in the file to read, or 
an attempt was made to write a record with a duplicate key 
to an indexed file. These are errors corresponding to FS 
codes '10' through '24' (see Section 8.5). 


3. DATA errors --— The data conversion routines failed because a 
record format was illegal; for instance, the program tried 
to read "ABC" into a numeric variable using a format such as 
###. These are errors that occur within the BASIC program; 
since they do not occur at the stage where data are actually 
transferred to or from a file, they do not change the File 
Status (FS) code for that file. 


4. IOERR errors --— Other input/output errors, such as physical 
errors operating the device, record-length errors, and file 
boundary errors. These are errors corresponding to FS codes 
'30' through '99.' 


The Data Management System attempts to resolve some I/O errors 
of the first category by means of a dialogue with the workstation 
operator at the time of the error. BASIC allows the user to specify 
program branches to be taken if a type EOD, DATA, or IOERR error 
occurs. Either a GOTO or a GOSUB exit can be used. If GOSUB is 
used, a RETURN statement at the end of the subroutine returns 
program execution to the statement following the file I/O statement 
that had the error. 


To specify error branching, the programmer specifies (1) the 
type of error situation to be covered (EOD, DATA, or IOERR), (2) the 
type of transfer of control to be performed (i.e., returning (GOSUB) 
or nonreturning (GOTO)), and (3) the BASIC line number or statement 
label to which control is to be passed. For instance, to force a 
returning branch to the statement labeled TURTLE if a data 
conversion error occurs, the programmer writes 


DATA GOSUB TURTLE 


in the READ or WRITE statement. 
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Error branches for type IOERR errors are specified in the SELECT 
statement. Any IOERR errors that occur on a given file number must 
transfer control to a single routine. Error branches for DATA 
errors are specified in the READ or WRITE statement. Different 
statements transfer control to different service routines in the 
event of a data conversion error. Error branches for EOD error 
conditions can be specified in a SELECT statement to apply to all 
reads and writes under that file number, or they can be specified in 
an individual READ or WRITE statement to apply to errors occurring 
as a result of that individual statement. If a READ or WRITE 
statement has an EOD exit, that exit overrides any transfer of 
control that may have been specified in the SELECT statement. 


The REWRITE, PUT, and GET statements can also specify an error 
branch for DATA errors. The SKIP statement can specify an error 
branch for EOD errors (which would occur if an attempt were made to 
skip (with the SKIP statement) past the limits of the file). 


If an EOD, DATA, or IOERR error occurs and the program has not 
specified an error branch, execution of the program is aborted. 


The service routines for EOD and IOERR type errors can examine 
the expression FS(#n), which returns the file status for the file 
currently open on UFB #n, to determine the exact cause of the error. 


8.7 EXAMPLES OF FILE I/0 


The example program below takes as input a consecutive file 
containing a list of names, addresses, and phone numbers. Each 
record of the file contains the following information in the 
indicated positions: 


Name: bytes 1 through 20 
Street: bytes 21 through 40 
City: bytes 41 through 50 
State: bytes 51 through 52 


Zip Code: bytes 53 through 57 
Area Code: bytes 58 through 60 
Phone: bytes 61 through 67 
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This program produces as output an indexed file containing those 
records that have their state fields (bytes 51 through 52) equal to 
"MA" . 


100 SELECT #1, "INPUT", CONSEC, RECSIZE=67, EOD GOTO NO MORE 
200 SELECT #2, "OUTPUT", INDEXED, RECSIZE=67, KEYPOS=1, KEYLEN=20 
300 DIM RECS 67 

400 

500 /* OPEN AND CLOSE INDEXED FILE TO CREATE IT SO THAT ENTRIES CAN 
600 BE WRITTEN IN ANY ORDER */ 

700 OPEN #2, OUTPUT, SPACE=100, FILE="BOSTON", LIBRARY="ADDRESS", ! 
800 VOLUME="DATA" 

900 CLOSE #2 

1000 

1100 /* OPEN BOTH FILES */ 

1200 OPEN #1, INPUT, FILE="USA", LIBRARY="ADDRESS", VOLUME="DATA" 
1300 OPEN #2, 10, FILE="MASS", LIBRARY="ADDRESS", VOLUME="DATA" 
1400 

1500 GET RECORD: 


1600 READ #1, RECS /* READ A RECORD FROM THE CONSEC FILE */ 
1700 IF STR(REC$,51,2)<>"MA" THEN GET RECORD /* EXAMINE STATE */ 
1800 WRITE #2, RECS /* WRITE TO INDEXED FILE IF STATE="MA" */ 
1900 GOTO GET RECORD /* GET ANOTHER RECORD */ 

2000 

2100 NO MORE: /* EXIT ROUTINE FOR EOD ON FILE #1 */ 


2200 CLOSE #1 
2300 CLOSE #2 
2400 

2500 END 


The two SELECT statements describe the two files to be used: 
file #1 is consecutive, file #2 is indexed; both have fixed-length, 
67-byte records. When and if an end-of-data (EOD) condition occurs 
on file #1, control passes to the statement labeled NO MORE. The 
primary key field for the indexed file (#2) begins at the first byte 
of each record, and is 20 bytes long. 


The first time an indexed file is opened for output (i.e., when 
it is created), any records written to it must be written in primary 
key sequence. If the records to be written to an indexed file are 
not in order the first time the file is to have data written to it, 
the file must be opened and closed in OUTPUT mode without writing 
any records to it, thus creating a file with zero records in it 
(lines 700 through 900). It can then be reopened in IO mode (line 
1300), which allows records to be written in any order. 


NOTE 


In general, it is preferable to write records to indexed 
files in key sequence, if possible. Writing records to 
a new indexed file out of sequence is much less 


efficient in terms of both processor time and disk 
Space, and is recommended only when it is not practical 
to write records in sequence. 
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Once both files are opened, a record (REC$) is obtained from the 
consecutive file (line 1600) and the two characters of its state 
field are tested to see if they are equal to "MA" (line 1700). If 
so, the record is written to the indexed file (line 1800); if not, 
the next record is read from the consecutive file (label GET RECORD; 
line 1500). This cycle continues until all of the records in the 
consecutive file have been read. The first READ operation after the 
last record has been read causes an EOD error condition to occur, 
and control passes to the statement labeled NO MORE (line 2100), as 
specified in the EOD clause of the SELECT statement. Both files are 
then closed (lines 2200 through 2300), and the program ends. 


Note that the first 20 bytes (the name field) of each record are 
designated as the primary key field for the indexed file in the 
SELECT statement for that file. Any subsequent read from the file 
MASS by primary key obtains the address records in alphabetical 
order of addressees' names. However, they may have been written in 
any order; the order in which they were written was determined 
simply by the order of their appearance in the consecutive file, 
which was arbitrary. (The indexed file was opened and then closed 
without writing any records, and then reopened, specifically to 
enable the program to write the records in any order.) 


Sorted lists can be made at some later time based upon the 
telephone area codes and zip codes of the addressees. Such sorting 
is simplified by establishing alternate keys in the indexed file 
corresponding to the area code and zip code fields of the records. 
This can be done by changing the SELECT statement for the indexed 
file to: 


200 SELECT #2, "OUTPUT", INDEXED, RECSIZE=67, KEYPOS=1, KEYLEN=20, ! 
220 KEYPOS=1, KEYLEN=20, /* PRIMARY KEY = NAME */! 
240 ALT KEY 1, KEYPOS=58, KEYLEN=3, DUP, /* KEY 1 = AREA CODE */ ! 
260 KEY 2, KEYPOS=53, KEYLEN=5, DUP /* KEY 2 ZIP CODE */ ! 


The file now has two alternate indices: alternate index 1, which 
indexes records by the 3-byte field starting at byte 58 of the 
record (the area code field, according to the convention above), and 
alternate index 2, which indexes records by the 5-byte field 
starting at byte 53 (the zip code field). Both indices allow 
duplicate keys (DUP), since there may be more than one entry with 
the same area or zip code. 


In order to insure that the records written to the file can be 
retrieved later by these alternate keys, the alternate key access 
mask must be set appropriately before any records are written. The 
usable keys are numbered 1 and 2. The binary value of the alternate 
key access mask should be set to 1100000000000000, which is C000 in 
hexadecimal (see the discussion of the MASK function in Section 8.5). 
Line 1800 can be changed to read: 


1800 WRITE #2, MASK=HEX(C000), REC$ 


8-20 


The following program produces a consecutive file containing all the 
records from the MASS file that have their area code fields equal to 
"617" (assuming the file MASS was written with alternate keys, as 
described above): 


100 SELECT #1, "INPUT", INDEXED, RECSIZE=67, ' 
200 KEYPOS=1, KEYLEN=20, /* PRIMARY KEY=NAME */ ! 
300 ALT KEY 1, KEYPOS=58, KEYLEN=3, DUP, /* KEY 1=ZIP CODE*/ ' 
400 KEY 2, KEYPOS=53, KEYLEN=5, DUP /* KEY 2=AREA CODE */ 
500 SELECT #2, "OUTPUT", CONSEC, RECSIZE=67 

600 

700 DIM RECS 67 

800 


900 OPEN #1, INPUT, FILE="MASS", LIBRARY="ADDRESS", VOLUME="DATA" 
1000 OPEN #2, OUTPUT, SPACE=200, FILE="AREA617", LIBRARY="ADDRESS", ! 
1100 VOLUME="DATA" 

1200 

1300 FIRST_IN: /* GET FIRST RECORD W/ALT KEY 1 = "617" */ 

1400 READ #1, KEY 1 = "617", REC$, EOD GOTO THE END 

1500 GOTO NEXT OUT 

1600 

1700 NEXT_IN: /* GET NEXT RECORD W/ALT KEY 1 = "617" */ 

1800 READ #1, REC$, EOD GOTO THE END 

1900 IF KEY(#1,1) <> "617" THEN THE END 

2000 

2100 NEXT OUT: /* WRITE THE RECORD OUT TO THE CONSEC FILE */ 
2200 WRITE #2, REC$ 

2300 GOTO NEXT_IN 

2400 

2500 THE END: 

2600 CLOSE #1 

2700 CLOSE #2 

2800 END 


In this case, the indexed file MASS is associated with the file 
number (UFB) #1. Note that the attributes specified in the SELECT #1 
statement (line 100) are exactly the same as those specified in the 
SELECT statement in the program that created the file MASS. 


After the alternate indexed file MASS and the consecutive file 
AREA617 are opened (lines 800 through 1000), records with alternate 
key 1 (area code field) are read from MASS one at a time (lines 
1300, 1700) and written to AREA617 (line 2000). Note that the 
program has two separate routines (labeled FIRST_IN and NEXT_IN) for 
reading the first and subsequent records. This is because any 
statement of the form READ #n, KEY m = alpha-exp reads only the 
first occurrence in the file of a record with alternate key m equal 
to alpha-exp. Any subsequent READ #n statement that does not 
specify an alternate key number reads the next occurrence of a 
record with the most recently specified alternate key. The most 
recently specified alternate key path (m) is the current “reference 
key" for a particular indexed file. To change the reference key for 
a file, it is necessary to execute a READ with a specified key. The 
primary key is considered to be key 0 (zero). 
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After each record is read, its first alternate key field is 
examined (line 1900). The first time a record is read with alternate 
key 1 not equal to "617", the program branches to the statement 
labeled "THE END". Both files are then closed (lines 2600 through 
2700), and the program ends. 
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CHAPTER 9 . 
DATA CONVERSION AND MATRIX STATEMENTS 


9.1 DATA CONVERSION STATEMENTS 


VS BASIC provides an extensive set of instructions designed 
specifically to simplify the task of converting data from one format 
to another, either to interpret information in a foreign format, or 
to pack data into a more efficient format for storage or 
transmission. The statements included in this special data 
conversion instruction set are summarized below: 


CONVERT ~- Converts a numeric value to an alphanumeric character 
string, and vice versa. 


HEXPACK, HEXUNPACK --— HEXPACK converts a character’ string 
representing hexadecimal digits into the binary equivalent of 
the digits. HEXUNPACK does the reverse. 


ROTATE[C] -- Rotates the bits of a single character or a string 
of characters. 


TRAN -- Utilizes a table-lookup technique to provide high-speed 
character conversion. 


These statements are discussed at length under their individual 
entries in Part II. 


In addition to the above statements, other VS BASIC instructions 
that may be useful in data conversion operations include the Boolean 
operations AND, OR, XOR, and BOOLh (discussed in Section 5.7), the 
alphanumeric functions BIN and VAL (discussed in Section 5.5, 
Section 5.6, and under their entries in Part II), and the binary 
arithmetic operations ADD and ADDC (discussed in Section 5.7 and 
under their entries in Part II). 


9.2 MATRIX STATEMENTS 


VS BASIC offers a set of matrix statements that perform 
operations on entire arrays. The matrix statements provide 15 
built-in matrix operations, summarized below by function. Detailed 
discussions of each can be found in Part II. 


9.2.1 Matrix I/O Statements 
BASIC provides two matrix I/O statements, described as follows. 


MAT INPUT -- Allows run-time input of numeric or alphanumeric 
array values. 


MAT PRINT -- Displays or prints one or more arrays. Matrices 
are printed row by row. 


Both MAT INPUT and MAT PRINT allow explicit redimensioning of 
arrays (see Subsection 9.2.4). 


9.2.2 Matrix Assignment Statements 
BASIC provides the following matrix assignment statements. 
MAT CON --— Sets every element of a numeric array to l. 
MAT= -- Replaces each element of a numeric or alphanumeric array 
with the corresponding element of a second array. The first 


array is redimensioned to conform to the second. 


MAT IDN -— Causes a (square) matrix to assume the form of the 
identity matrix. 


MAT READ -—— Assigns values contained in DATA statements to array 
variables without referencing each member of the = array 
individually. 


MAT TRN -- Causes a numeric or alphanumeric array to be replaced 
by the transpose of a second array. The first array is 
redimensioned to correspond to the transpose of the second. 


MAT ZER —-— Sets every element of an array to zero. 


All of the matrix assignment statements listed above allow 
explicit redimensioning of arrays. See Subsection 9.2.4. 


9.2.3 Matrix Arithmetic and Sorting Statements 


BASIC provides the following matrix arithmetic and _ sorting 
statements. 


MAT + —- Adds two numeric arrays of the same dimension. 

MAT - -- Subtracts numeric arrays of the same dimension. 

MAT ()* -- Multiplies each element of a numeric array by an 
expression. 

MAT * -- Stores the product of two numeric arrays in a third 
array. 


MAT INV -- Replaces one numeric matrix with the inverse of 
another. 


MAT ASORT, MAT DSORT --— Sorts one alphanumeric or numeric array 
in ascending or descending order into a second array. 


Operations are performed on numeric arrays according to the 
rules of linear algebra, and can be used for the solution of systems 
of nonsingular homogenous linear equations. Inversion of matrices 
can be done in significantly less time than is possible with 
ordinary BASIC statements. MAT operations on alphanumeric arrays 
can be used for simple and rapid I/O (input/output) and printing of 
alphanumeric material. 


Note that the arithmetic and sorting statements described above 
do not allow explicit redimensioning of arrays. 


9.2.4 Array Dimensioning 


Both numeric and alphanumeric arrays can be manipulated with MAT 
statements. If not dimensioned in a DIM or a COM statement, arrays 
are given default dimensions of 10 by 10, with a default alphanumeric 
element length of 16 bytes. Each dimension can range from 1 to 
32,767, with an alpha element length of 1 to 256 bytes. 


The dimensions of an array can be changed explicitly using the 
MAT REDIM statement. This can also be done by adding the new 
dimensions, enclosed in parentheses, after the array name in any of 
the following MAT statements: 


MAT CON 
MAT IDN 
MAT INPUT 
MAT READ 
MAT ZER 


Arrays can also be redimensioned implicitly, as shown in the 
following example. 


100 DIM A(10,10),B(2,2) ,C(2,2) 
200... 
400 MAT A=B+C 


The array A is redimensioned at statement 400 from a 10 by 10 array 
to a 2 by 2 array. 


For alphanumeric arrays, the maximum length of each element can 
be changed by specifying the new length after the dimension 
specification. For example: 

MAT REDIM A$(2,3)10 
redimensions the array A$ to be two rows by three columns with the 


Maximum length of each element in the array equal to 10. 
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NOTE 


With either explicit or implicit redimensioning, the 
newly-—dimensioned array must not require more space than 
was required for its original dimensions. For numeric 


arrays, this implies the same (or fewer) elements. For 
alphanumeric arrays, there must be the same number (or 
fewer) characters. 


9.2.5 Matrix Statement Rules 


The following rules must be observed in the use of matrix 
statements: 


ite 


2. 


Each matrix statement must begin with the word MAT. 


Multiple matrix operations are not permitted in a single MAT 
statement. For instance, MAT A = B+C-D is invalid. The same 
result can be achieved by using two MAT statements: 
MAT A = B+C and MAT A = A-D. 


Arrays that contain the result of certain MAT statements are 
automatically redimensioned; other arrays can be 
redimensioned explicitly in the MAT REDIM statement. A 
redimensioned numeric array cannot contain more elements than 
given in its original definition; a redimensioned 
alphanumeric array also cannot contain more characters than 
given in its original definition. 


A vector (a singly-subscripted array) cannot be redimensioned 
as a matrix (a doubly-subscripted array), nor can a matrix be 
redimensioned as a vector. 


The same array variable cannot appear on both sides of the 
equation in matrix multiplication, matrix transposition, or 
Matrix sorting. MAT C=A*B and MAT A=TRN(C) are valid MAT 
statements; MAT C=C*B and MAT B=TRN(B) are not. 


The following rules are used in the syntax specifications to 
describe BASIC program statements and system commands: 


Ls 


Uppercase letters (A through Z), digits (0 through 9), and 
special characters (“, /, +, etc.) must be written exactly 
as shown in the general form. 


Lowercase words represent items that are supplied by the 
user. 


Items in square brackets ([]) indicate that the enclosed 
information is optional. For example, the general format 
RESTORE [expression] indicates that the RESTORE statement 
can be optionally followed by an expression. 

Braces ({}) enclosing vertically stacked items indicate 
alternatives; one of the items is required. For example, 

literal it 
operand = alpha variable 


expression J 


indicates that the operand can be either a literal, an alpha 
variable, or an expression. 


Ellipses (...) indicate that the preceding item can be 
repeated as necessary. For example, 


INPUT [literal,] receiver [,receiver]... 


indicates that additional receivers can be added to the 
INPUT statement as needed. 


The order of parameters shown in the general format must be 
followed. 
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ABS Function 


General Format: 


ABS (numeric exp) 


ABS returns the absolute value of the numeric expression 
specified as its argument. The value returned by the ABS function 
is of the same type (integer or floating-point) as the argument. 


Example: 
10 A= 47 
20 B=-A 


30 Print A, B, ABS(B) 
Result: 


47 —47 47 
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ACCEPT Statement 


General Format: 


ACCEPT list [list]... | KEYS (alpha-arg1)] [,KEY (numeric variable)] 


GOTO line number line number 
| on alpha-arg2 esse} peat a |. { statement son} 
WALT 
GOTO line number 
‘NOALT one etc ap 


where: 


list = literal 


AT (exp2, exp3) { 
[FAC (alpha-arg3),] 


num-variable [,PIC (image)][,num-spec] 
alpha-variable [,CH(int)]L.alpha-spec] 


(POS) 
num-spec = RANGE < (NEG) 


(exp4, exp5) 


alpha-spec = RANGE (alpha-arg4, alpha-arg5) 
image = a valid numeric image, as in FMT 
int = an integer specifying the length of the (alpha) field 


alpha-arg = literal, alpha-variable, BIN function, STR function 


The ACCEPT statement is discussed in detail in Section 7.5. A 
summary of the features and operation of ACCEPT follows. 


The ACCEPT statement allows workstation input of numeric and 
alphanumeric data in a field-oriented manner, using the supplied 
formatting information. Both single receivers and arrays can be 
entered. 


ACCEPT uses the entire screen, clearing all unused areas. 
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Field Descriptions 


Ly 


Numeric fields can be formatted according to the PIC() 
specification. It is interpreted as in the FMT statement 
(see FMT statement). If PIC() is omitted, the numeric 
fields are 18 characters. All blanks appear on the screen 
as pseudoblanks. 


Alphanumeric field width is specified by CH(int), where int 
= field width. If CH is omitted, the field size defaults to 
the defined length of the alpha value. All blanks appear as 
pseudoblanks on the screen. 


Field Attribute Characters (FACs) 


Ls 


If omitted, the following defaults are assumed: 


Alphanumeric -— bright, modifiable, uppercase, no underline 
(HEX(81)). 


Floating-point -- bright, modifiable, uppercase, no underline 
(HEX(81)). 


Integer -- bright, modifiable, numeric only, no _ underline 
(HEX(82)). 


The first character of the alpha-expression specified in the 
FAC clause (alpha-arg3) is used as the FAC character. 


Field Placement Order 


1. 


For single receivers, the fields are placed one at a time in 
order of appearance in the statement, or in the order 
implied by any AT clauses that are used. 


For arrays, the fields are arranged element by element, in 
the usual row-by-row order (like MAT PRINT). 


Field Positioning 


A field can be explicitly placed at a specified row and column 
on the screen, using the AT clause of the ACCEPT statement. If no 
AT clause is given, the field is placed according to the defaults 
used by ACCEPT. These are as follows: 


, 


If the field can fit on the same line as the preceding 
field, it will follow directly after the preceding field 
with space for one FAC left between the fields. If the 
field in question is the first field on the screen (i.e., 
there is no preceding field), then it is placed by default 
at row 1, column 2, to leave room for a preceding FAC. 


II-5 


Any modifiable field that is too long to fit in the space 
remaining on the line containing the preceding field is 
placed at the beginning of the second column of the next 
line on the screen. A modifiable field must not be too long 
to fit on a single line (79 bytes maximum length). 


Any protected field that is too long to fit on the same line 
as the preceding field, but is no longer than 79 bytes, is 
placed at the beginning of the second position on the 
following line. If it is longer than 79 bytes, it is placed 
immediately following the preceding field, and continues 
onto as many lines as necessary. 


If a protected field is too long to fit on the line on which 
it starts, it continues for as many lines as necessary. 
Each new line begins with a FAC with the same attributes as 
the FAC that comes at the beginning of the field, except 
that the user cannot tab to continued sections of the field. 


These rules are summed up in Table II-1. 


The following conditions are considered errors, whether they 
occur because the field was placed using an AT clause, or because 
the field was placed by the ACCEPT defaults: 


1. 


2. 


3% 


4. 


Any modifiable field longer than 79 bytes (too long to fit 
on a single line). 


Any explicitly-positioned modifiable field extending beyond 
the end of the line on which it is placed. 


Any explicitly-placed field that starts beyond’ the 
boundaries of the screen. 


Any field extending beyond the end of the last line on the 
screen. 


For arrays, the cursor automatically moves to column 2 of the 
next line on the screen after each row. 
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Table II-1. ACCEPT Field Placement Defaults 


Line Length Modifiable Field Protected Field 


Less than 79 
characters 


fits Immediately follows Immediately follows 
on line previous field previous field 


does not fit Begins on next line Begins on next line 
on line 


More than 79 Not allowed Immediately follows 
characters previous field 


Validation 


Data entered by the user in response to an ACCEPT screen can be 
validated by either character type or value. Character type 
validation is controlled by the FAC clause. The FAC that precedes a 
field determines which types of characters (i.e., numeric only, all 
characters, uppercase only) can be typed in that field. Attempting 
to type in any character prohibited by that field's FAC causes the 
workstation alarm to sound, and the character is ignored. 


Both numeric and alphanumeric fields can be validated by the 
BASIC program, according to a specified range of values, before 
being accepted. If validation fails, the first incorrect field is 
set to blinking and the user is  reprompted for the values. 
Validation is done via a range specification as follows: 


1. Numeric 
RANGE: POS = positive values (including zero). 
NEG = negative values only. 
exp4, exp5 = lower and upper limits, respectively, 
for the input value(s) (inclusive). If a negative 


value is specified for a limit, the expression must 
be placed in parentheses. 


2. Alphanumeric 


RANGE: alpha expl, alpha exp2 = lower and upper limits. 
The ASCII collating sequence is used. 
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PF Key Control 


The action taken by the program in response to ENTER and PF keys 
can be controlled by any combination of three key control clauses. 
(PF keys in ACCEPT statements do not call DEFFN' subroutines or 
strings.) If all three clauses are omitted, only the ENTER key can 
be used to respond to the ACCEPT. If any clause is present, ENTER 
and all PF keys are allowed by default, subject only to the 
restrictions of the KEYS clause if present. The three key control 
clauses are: 


1. KEYS -- This clause specifies the keys that are valid for 
this ACCEPT; if any others are pressed, the workstation 
alarm sounds. The alpha-expression (actual length) is used 
as a list of 1-byte binary values corresponding to the 
allowed PF key (ENTER = 00). Invalid values are ignored. 
(PF32 = HEX(20) may be considered to be a trailing blank if 
the user is not careful.) The key order is irrelevant. 


2. KEY -- This causes the number of the key (ENTER = 0) pressed 
by the user to be placed in the numeric variable. This is 
done prior to any field validation or exit branching. The 
KEYS clause takes precedence over the KEY clause. 


3. ON Key Value -- This clause allows the user to exit without 
changing any data values if certain PF keys are specified. 
As in the KEYS clause, the alpha-expression (actual length) 
is treated as a PF key list. Each entry in the list 
corresponds to a line number or statement label to which the 
program branches if that PF key is pressed. The last line 
number should not be followed by a comma, nor should unused 
line numbers or statement labels be specified. 


Response to Modification of Data 


1. Ordinarily, all modifiable fields are read, validated, and 
transferred to their receivers, whether or not the fields 
were actually changed by the user. This can be made more 
efficient via the ALT specification or the NOALT clause. 
The presence of either ALT or the NOALT exit in the ACCEPT 
statement causes only those fields that were altered by the 
user (i.e., character keystrokes detected at the 


workstation) to be processed. Unaltered fields’ are 
effectively ignored, and the corresponding receivers are 
unchanged. 


2. If NOALT is specified and no fields were altered, the 
specified exit is taken. 


3. If ALT is specified, only those fields that were altered are 
processed; however, an exit cannot be specified. 
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Execution of ACCEPT 


i 


The screen is generated as described, with the cursor 
positioned at the first modifiable (or numeric—protected) 
field, if any. All fields contain the current values of the 
receivers/array elements. 


The user can enter new values. When ENTER is keyed, or a PF 
key is pressed, the key is first checked for validity. If 
invalid, the workstation alarm _ sounds. The user can 
continue to modify or can press another key. 


If the key is specified in the ON clause, the specified 
branch is taken without any field reads or verification. 
(The KEY variable contains the key number, in any case.) 


Otherwise, all modifiable fields (or only altered fields if 
ALT or NOALT is specified) are read/validated. Numeric 
fields are validated for proper numeric format independently 
of RANGE validation. Although any PIC specification can be 
used, special characters (CR,DB, etc.) are not valid on 
input. 


If any field is invalid, its FAC is set to blinking. The 
user must correct the mistake, and can further change other 
fields. 


Syntax Example: 


300 
310 
320 
330 
340 
350 


ACCEPT AT (12, 15), A, PIC(###), RANGE(50,100), 
FAC(HEX(91)), B$, CH(7), RANGE("BARRELS", "KEGS"), 
"OF BEER ON THE WALL.", 

KEYS (BIN(O) & BIN(1) & BIN(16)), KEY(OPTION), 
ON (BIN(1) & BIN(16)) GOTO START, FINISH, 
NOALT GOSUB 1700 
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ADD[C] Logical Operator 


General Format: 


[LET] alpha-receiver = [logical exp] ADDIC] logical exp 


logical exp: see Section 5.7 


The ADD operator is used to add a binary value to the binary 
value of an alpha variable. For example, in the statement 


100 A$ = ADD B$ 


the binary value of B$ is added to the binary value of A$, and the 
result is stored in A$. 


If an operand is specified before the ADD operator (operand-1), 
its value is stored in the receiver variable prior to performing the 
addition. For example, in the statement 


100 A$ = C$ ADD BS 


the value of C$ is first stored in A$; the value of B$ is then added 
to A$, and the result is stored in A$. The contents of operand—l 
and the operand that follows the ADD operator (operand-2) are not 
altered. 


If C does not follow the ADD operator, the addition is carried 
out on a character-by-character basis from right to left, with no 
carry propagation between characters. That is, the rightmost byte 
of the value of the operand is added to the rightmost byte of the 
receiver variable, the next-to-last character of the operand is 
added to the next-to-last character of the receiver, and so forth. 
For example: 


100 DIM A$2 

200 A$=HEX(0123) 

300 A$=ADD HEX(OOFF) 

400 PRINT "RESULT = ";HEXOF(A$) 


Output: RESULT = 0112 


If the operand and receiver are not of the same defined length, 
the shorter one is left-padded with hex zeros. The result is 
right-justified in the receiver, with high-order’ characters 
truncated if the result is longer than the receiver. 


If C does follow ADD, the value of the operand is treated as a 


single binary number and is added to the binary value of the 
receiver variable with carry propagation between characters. 
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For example: 
100 DIM A$2 
200 A$=HEX(0123) 
300 A$=ADDC HEX(OO0FF) 
400 PRINT "RESULT = '";HEXOF(A$) 
OUTPUT: RESULT = 0222 
See Section 5.7 for more information. 
Syntax Examples: 
600 A$=ADD HEX(FF) 
200 A$=ADDC ALL(FF) 


900 STR(A$,1,2)=B$ ADDC C$ 
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ALL Function 


General Format: 


ALL (alpha-exp) 


The ALL function creates a string consisting entirely of 
characters equal to the first character of the alpha-expression, and 
has a length equal to the defined length of the receiver. It is 
used only in logical expressions. (For more information on the use 
of the ALL function, see Section 5.7.) 


syntax Examples: 
400 LET A$=ALL(B$) 


800 C$=AND ALL(D$) 
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AND Logical Operator 


General Format: 


[LET] alpha-receiver = [logical exp] AND logical exp 


logical exp: see Section 5.7 


The AND operator performs a logical AND operation on two or more 
alphanumeric arguments. 


The operation proceeds from left to right. If the operand (the 
logical expression) is shorter than the receiver, the remaining 
characters of the receiver are left unchanged. If the operand is 
longer than the receiver, the operation stops when the receiver is 
exhausted. 


See Section 5.7 for more information. 


syntax Examples: 


100 A$ = AND B$ (logically ANDs A$ and B$ and places the result 
in A$.) 


BS AND C$ (logically ANDs B$ and C$ and places the 
result in A$.) 


100 A$ 


Numeric Examples: 


HEX(OFOF) AND HEX(OFOF) =HEX(OFOF) 
HEX(OOFF) AND HEX(0OFOF)=HEX(000F) 
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ARCCOS Function 


General Format: 


ARCCOS (numeric exp) 


The ARCCOS function returns the arccosine of its argument; this 
is the inverse function of COS. The value of the numeric expression 
used as an argument to ARCCOS must be between 0 and 1 (inclusive); 
otherwise, an error message results when the ARCCOS function is 
evaluated and program execution halts. ARCCOS returns a_ floating- 
point value in radians, degrees, or grads, depending on the 
trigonometric mode specified by the most recently executed SELECT 
statement. The default. is radians if no SELECT was executed. 


Syntax Example: 
100 LET X = ARCCOS(Y) 


Numeric Examples: 


ARCCOS (0) 
ARCCOS (1) 


90 (degrees) 
0 
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ARCSIN Function 


General Format: 


ARCSIN (numeric exp) 


The ARCSIN function returns the arcsine of its argument; this is 
the inverse function of SIN. The value of the numeric expression 
used as an argument to ARCSIN must be between 0 and 1 (inclusive); 
otherwise, an error message results when the ARCSIN function is 
evaluated and program execution halts. ARCSIN returns a floating- 
point value in radians, degrees, or grads, depending on the 
trigonometric mode specified by the most recently executed SELECT 
statement. The default is radians if no SELECT was executed. 


Syntax Example: 
100 LET X = ARCSIN(Y) 


Numeric Examples: 


ARCSIN(0) 
ARCSIN(1) 


0 
90 (degrees) 


TL=t5 


ARCTAN Function 


General Format: 


ARCTAN (numeric exp) 


The ARCTAN function returns the arctangent of its argument; this 
is the inverse function of TAN. ARCTAN returns a floating-point 
value in radians, degrees, or grads, depending on the trigonometric 
mode specified by the most recently executed SELECT statement. The 
default is radians if no SELECT was executed. 


Syntax Example: 
100 LET X = ARCTAN(Y) 


Numeric Examples: 


ARCTAN (1) 
ARCTAN (0) 


45 (degrees) 
0 
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ATN Function 


General Format: 


ATN(numeric exp) 


The arctangent function; synonymous with ARCTAN. 
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BIN Function 


General Format: 


BIN (exp [,d]) 


where: 
d = 1,2,3,4 (default = 1) 


This function converts the integer value of the expression to a 
d-character alphanumeric string that contains the binary equivalent 
of the expression. BIN is the inverse of the function VAL. 


For d = l, 2, or 3, the expression is converted to a d-byte 
unsigned binary number. The limits for the value of the expression 
are: 


256 (d=1) 
0 <= value expression <= 65536 (d=2) 
16777216 (d=3) 

For d=4, the expression is converted to a 4-byte two's-complement 


signed binary number (like internal integer format). The range is 
—2147483648 <= value of expression <= 2147483647 


Syntax Examples: 
300 A$=BIN(A, 4) 
800 B$S=BIN(A,3) AND BIN(B,3) 


Numeric Examples: 


BIN (255,1) = HEX(FF) 


BIN (65535,2) HEX (FFFF) 


BIN (32767,3) = HEX (007FFF) 
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BOOLh Logical Operator 


General Format: 


[LET] alpha-receiver = [logical exp] BOOLh logical exp 


logicalexp: see Section 5.7 
h = a digit from O to 9, or a letter from A to F 


BOOL is a generalized logical operator that performs a specified 
operation on the value of the receiver alpha variable. The 
operation to be performed is specified by the hexadecimal digit 
following BOOL (see Table II-2). BOOL can be used only in the 
alpha-expression portion of an assignment statement (1.e., on the 
right-hand side of the equals (=) sign). The value of the operand 
that follows the BOOLh operator (operand-2) and the value of the 
receiver variable are operated upon, and the result is stored in the 
receiver variable. For example, the statement 


100 A$ = BOOL7 BS 


logically not-ANDs the value of B$ with the value of A$, and stores 
the result in A$. 


If an operand (operand-1) precedes the BOOLh operator, its value 
is stored in the receiver-variable_ prior to performing the specified 
logical operation. For example, the statement: 


200 A$ = C$ BOOL7 B$ 


first stores the current value of C$ into A$, and then not-ANDs the 
value of BS to A$. Again, the result of the operation is stored in 
A$. The contents of operand-1 and operand-2 are not affected by the 
operation. 


In every case, the logical operation to be performed is 
identified by the hexadecimal digit following BOOL. Sixteen logical 
operations are available (see Table II-2). The hexadecimal digit 
used to identify each operation is a kind of mnemonic. that 
represents the logical result of performing the operation on the 
following bit combinations: 


receiver-variable: 1100 
operand-2: 1010 


For example, the hexadecimal digit E identifies the OR operation. 
When 1100 is ORed with 1010, the result is 1110, or hexdigit E. 
Several commonly used BOOL operations are available as separate 
operators: BOOLE is equivalent to OR, BOOL6 to XOR, and BOOL8 to 
AND. 
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Table II-2. Logical Operations 


Logical Operation 
(Note: iff = if and only if) 


null (bits always = 0; logical inverse of BOOLF) 


not-OR (1 iff corresponding bits of both 
arg 1 and arg 2=0) (NOR) 


(1 iff corresponding bits of arg 2=1 and arg 1=0) 


binary complement of arg 1 (1 iff bit of 
arg 1=0; otherwise 0) 


(1 iff corresponding bits of arg 2=0 and arg 1=1) 
binary complement of arg 2 (1 iff bit of arg 2=0) 


exclusive OR (1 iff corresponding bits of 
arg 1 and arg 2 are different) (XOR) 


not-AND (0 iff corresponding bits of both 
arg 1 and arg 2=1) (NAND) 


AND (1 iff corresponding bits of both arg 1 and 
arg 2=1) 


equivalence (1 iff corresponding bits are the 
same, i.e., both = 1 or both = 0) 


arg 2 (identical to bits of arg 2) 


arg 1 implies arg 2 (1 unless arg 1=1 and 
arg 2=0) 


arg 1 (identical to bits of arg 1) 


arg 2 implies arg 1 (1 unless arg 2=1 and 
arg 1=0) 


OR (1 unless both corresponding bits = 0) 


identity (bits always = 1; logical inverse 
of BOOL(0)) 


BOOL6 is equivalent to XOR; BOOL8 is equivalent to AND; BOOLE is 


equivalent to OR. 


Numeric Examples: 


HEX(F000)=HEX(OFOF) BOOL1 HEX(OFFO) 
HEX(FOOF)=HEX(OFOF) BOOL5S HEX(0OFFO) 
HEX (FFFF )=HEX(OFOF) BOOLF HEX(OFFO) 
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CALL Statement 


General Format: 
CALL “name” [[ADDR](argLarg]...)] 


where: 
“name” 


= 1 to 8 alphanumeric characters (including @, #, $) 
= SUB “name” of the SUB program being called 


exp 

alpha-exp 
array-designator 
file-exp 


Name must be enclosed in quotation marks 


CALL directs execution to the named subroutine, identified by a 
SUB statement, and passes any arguments to the subroutine program 
dummy arguments. The subroutine must be linked, using the LINKER 
utility, before the program is run. This can also be done when a 
program is compiled from the EDITOR. 


The argument list in the CALL statement must correspond 
item—-for-—item with the argument list in the SUB statement, as shown 
in Tables II-3 and II-4. . 


Table II-3. Argument Correspondence 


CALL argumen SUB argument 


(alpha—) expression scalar variable 
matrix matrix 

vector vector 
file-—expression file—number 


Table II-4. Argument Type Correspondence 


CALL argument type SUB argument type 


alpha alpha 


floating-point floating-point 
integer integer 
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A SUB statement with an argument list as follows 
100 SUB "HENRY" (ATLANTIS$, ELASMOBRANCH, JELLYFISH%(), #1) 


must have arguments passed to it by a CALL statement in exactly the 
same order -- in this case, alphanumeric scalar, floating-point 
variable, integer array-designator, file~expression. The arguments 
in the CALL statement do not have to be identical to those in the 
SUB statement, but each must correspond to the argument in the same 
position in the SUB statement's argument list. Thus, the following 
CALL statement is valid: 


CALL "HENRY" (STR(C1$()), A(1), BZC ), +N) 


Note that STR(C1$()) is used as a string since C1$() would be 
treated as an alpha array-—designator. 


Argument passing for the CALL statement proceeds as follows: 


1. Values of file-expressions are passed to the SUB program to 
replace dummy file numbers (specifically, the UFB address is 
passed to the SUB program). 


2. Pointers to the values of numeric scalar variables are 
passed to the SUB program. 


Non-ADDR Type 


Array and alphanumeric scalar descriptors are passed to the SUB 
routine, including pointers to the storage addresses, dimensions and 
lengths. Since other numeric expressions and alpha expressions are 
not receivers, their values must be computed and stored in temporary 
locations, along with their lengths, if alphanumeric. Pointers (in 
the case of numeric expressions) or descriptors of the temporary 
values (in the case of alphanumeric expressions) are then passed to 
the SUB program. Otherwise, execution proceeds as with arrays and 
receivers, except that returned values and lengths are effectively 
lost, since the locations are no longer accessible to the calling 


program. 


ADDR Type 


All data types, pointers to the storage addresses only are 
passed; no dimensioning or length specifications are passed to the 
subroutine. (For numeric scalars and file-numbers, this is 
identical to the non-ADDR type.) Changed values are accessible as 
with the non-ADDR type, except that array dimensions and lengths can 
be changed only within the subroutine (1.e., array dimensions and 
lengths return to their original values after the subroutine returns 
to the calling program). 
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NOTE 


ADDR-type CALL is generally used only when the called 
subroutine is non-BASIC; otherwise, standard (non-ADDR) 


CALLs should be used. 


syntax Examples: 


100 CALL "ELIOT"(B,C$,D%) 
200 PRINT "RETURNED" 
300 STOP 


100 DIM A$24 

200 CALL "EXTRACT" ADDR("NA",AS$) 
300 PRINT A$ 

400 STOP 


100 DIM LONG$100 

200 CALL "123456" (LONG$) 
300 PRINT LONG$ 

400 STOP 
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CLOSE Statement 


General Format: 


file-exp 
WS 

CRT 
PRINTER 


CLOSE 


This statement closes a file that had been previously opened for 
I/O operations by an OPEN statement. If the file is subsequently 
reopened in the program with another OPEN statement, the file, 
library, and volume need not be respecified by the program or the 
user. 


Attempting to close a file that was not previously opened by an 
OPEN statement causes a nonrecoverable program error at run time. 
All files are closed at the start of the program; opened files 
should be closed before the end of the program. 


CLOSE CRT allows the user to close the workstation. This is 
necessary if the user calls another program that attempts to OPEN 
the workstation. CLOSE CRT is equivalent to CLOSE WS. 


CLOSE PRINTER is used. to close the standard VS PRINT file 
selected by the SELECT PRINTER statement. Subsequent output to this 
device in the same run is directed to another standard VS PRINT 
file. If the standard VS PRINT file is already closed, this 
statement has no effect. 


Syntax Examples: 


100 CLOSE #1 
300 CLOSE #A 
500 CLOSE #LEN(A$) 
700 CLOSE CRT 
900 CLOSE PRINTER 


PRINTER Programming Note 


On program entry, the workstation is the default output device 
and the standard VS PRINT file is closed. If a SELECT PRINTER 
statement is executed, subsequent PRINT [USING] output is directed 
to the standard VS PRINT file. This standard file is implicitly 
opened the first time any output is generated by a PRINT [USING] 
statement following the execution of the SELECT PRINTER statement. 
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Several standard VS PRINT files can be created during a single 
program run. These multiple files can have different printline 
width specifications. The CLOSE PRINTER statement must be executed 
to signal the end of output to the open standard VS PRINT file, and 
the SELECT PRINTER option with a new width specified must be in 
effect for the next PRINT [USING] to be automatically routed to 
another standard VS PRINT file. Any attempt to alter the printline 
width while the standard VS PRINT file is open produces a run-time 
error. To redirect output.to the workstation, a SELECT CRI or 
SELECT WS statement must be executed. 
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COM Statement 


General Format: 


COM com element [,com element]... 


where: 

numeric scalar variable 

numeric array name (int Lint]) 

alpha scalar variable [length-integer] 
alpha array name (int Lint])[length-integer] 


com element = 


1 <=length-integer <= 256 
1 <=int <= 32767 


The COM statement is a nonexecutable statement defining scalar 
variables or arrays to be used in common by several program 
segments. The COM statement is also discussed in Subsection 6.5.4. 


This statement provides array definition identical to the DIM 
Statement for array variables; a single COM statement can combine 
declarations of array variables (e.g., A(10), B(3,3)) and scalar 
variables (e.g., C2,D,X$). 


Common variables must be defined before they are _ used. 
Therefore, it may be convenient to define the common variables at 
the beginning of the program. 


If a particular set of common variables is to be used in each of 
several sequentially called subprograms, the COM statement must be 
included in the main program and each subprogram in which they are 
used. All variables in the COM statements must be declared in the 
same order, and with the same dimensions and lengths, in each 
separately compiled module. 


The COM statement can be used to set the maximum defined length 
of alphanumeric variables (assumed to be 16 if not specified). The 
length integer (<=256) following the alpha scalar (or alpha array) 


variable specifies the length of that alpha variable (or those array 
elements). 


Syntax Examples: 
800 COM A(10),B(3,3),C2 
200 COM C,D(4,14),E3,F(6),F1(5) 
600 COM M1$,M$(2,4),X,Y 


300 COM A$10,B$(2,2)32 
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CONVERT Statement 


General Formats: 


GOTO line number 


CONVERT alpha-exp TO numeric variable | ,DATA GOSUB statement label 


or 


CONVERT numeric exp TO alpha-receiver, PIC (image) 


+ 
ttt] | 


where: 


~ WOW *tO* 


image = [+][$] | 


where either a leading or a trailing sign can be used, but not both 


- 


The CONVERT statement is used to convert alphanumeric 
representation of numeric data to internal numeric format, and vice 
versa. Two forms of the statement are provided. 


Form 1: Alpha-to—Numeric Conversion 


Form 1 of the CONVERT statement converts the number represented 
by ASCII characters in the alphanumeric expression to a numeric 
value and sets the numeric variable equal to that value. For 
example, if A$ = "1234", CONVERT A$ TO X sets X = 1234. An error 
results (or the data exit is taken) if the ASCII characters in the 
specified alphanumeric are not a legitimate BASIC representation of 
a number. 


Alpha-to-numeric conversion is particularly useful when numeric 
data is read from a peripheral device ina record format that is not 
compatible with normal BASIC statements, or when a code conversion 
is first necessary. It can also be useful when it is desirable to 
validate keyed-in numeric data under program control. (Numeric data 
can be received in an alphanumeric variable, and tested with the NUM 
function before conversion to numeric format. ) If the 
alpha-expression is entirely blank, an error results (or the data 
exit is taken). 
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Form 2: Numeric-to—Alpha Conversion 


Form 2 of the CONVERT statement. converts the numeric value of 
the specified expression to an ASCII character string according to 
the image specified. Numeric-to-alpha conversion is particularly 
useful when numeric data must be formatted in character format in 
records. 


The image used with this form of CONVERT is used in the same way 
as a format-spec in a FMT statement. For example, the statement 


100 CONVERT 10 to A$, PIC (+#4#) 


results in AS =" 10". 


Syntax Examples: 


Alpha to Numeric: 


100 CONVERT A$ TO X 
200 CONVERT STR(A$,1,NUM(A$)) TO X(1) 


Numeric to Alpha: 


100 X¥ = 12.195 

200 CONVERT X TO A$, PIC (000) 
(result: A$ = "012") 

300 CONVERT X*2 TO A$, PIC (+##.#+#) 
(result: A$ = "4+24.39") 

400 CONVERT X TO STR(A$,3,8), PIC (-#.#TTTT) 
(result: STR(A$,3,8) = " 1.2E+01") 

500 CONVERT X TO A$, PIC (0000. ###+#+#) 
(result: A$ = "0012.19500") 
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COPY Statement 


Genera! Format: 


COPY [-] alpha-exp TO [-] alpha-receiver 


COPY transfers the alpha-expression to the alpha-receiver, one 
byte at a time, using the defined lengths of both. 


If "a is specified before the alpha-expression, the 
alpha-expression is sent from right to left, starting at the 
rightmost byte of the expression. Similarly, if "-" is specified 


before the alpha-receiver, the alpha-expression is received from 
right to left, starting at the rightmost byte of the receiver. 


If "-" is not specified before the alpha-expression, the 
alpha-expression is sent from left to right, starting at _ the 
leftmost byte of the expression. Similarly, if "-" is not specified 


before the alpha-receiver, the alpha-expression is received from 
left to right, starting at the leftmost byte of the receiver. 


Transfer stops when the receiver is filled or the expression is 


exhausted. If the expression is exhausted, the remainder of the 
receiver is filled with blanks. 


NOTE 


If the alpha-expression is a receiver, it is copied 
directly from its memory location; otherwise, the value 
of the alpha-expression is stored into a temporary 


location and copied from _ there. Thus, copying a 
receiver onto itself can result in  single-character 
propagation or other position-dependent results. 


Syntax Examples: 


100 A$="CHART" 

200 COPY A$ TO B$ 
(result B$="CHART") 

300 COPY -A$ TO B$ 
(result B$="TRAHC" ) 
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COS Function 


General Format: 


COS (numeric exp) 


The COS function returns a floating-point value that is the 
cosine of the numeric expression specified as its argument. The 
expression is in units of radians, degrees, or grads, depending on 
the trigonometric mode specified by the most recently executed 
SELECT statement. If no SELECT statement was executed in the 
program or subprogram, the default mode is radians. 


Syntax Example: 
100 X = COS(Y) 


Numeric Examples: 


COS(90) = 0 (assuming the calculation is performed in degrees) 
Cos(0) = 1 
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CVDQ Subroutine 


General Format: 


CALL “CVDQ” ADDR (floatbin_variable) 


The CVDQ subroutine converts the value of an input variable from 
the float binary to the float decimal representation. The CVDQ 
subroutine is useful for cases where a module compiled with float 
binary numerics must pass float values to or share a common float 
variable with a module compiled with float decimal numerics. 


CVDQ returns the float decimal value to the input variable, 
destroying the previous contents of the variable. Because the float 
decimal representation has a smaller range of legal values than 
float binary, the input float binary value must be in the following 
range: 


-1.0E+63 < float_bin variable < 1.0E+63 


Input values outside this range result in either a compile-time 
warning or a program check. In addition, positive or negative 
fractional values smaller than + 1E-65 cannot be represented in 
float decimal. Input values outside this range produce an exponent 
underflow compile-time warning or run time program check. The input 
variable must be float binary; if the user passes a float decimal 
value to CVDQ, an incorrect float decimal value is returned. 


CVDQ is an external subroutine, and must be called with the ADDR 
form of the CALL statement (refer to Subsection 6.5.4 for details). 
In addition, programs calling CVDQ must link to the System Library 
(@SYSTEM@) on the System Volume. Consult the VS Program Development 
Tools for details on the LINKER utility. 


NOTE 


The CVDQ subroutine cannot be used on VS-80 or VS-50 


systems, since these systems do not support float decimal 
numerics. 


Syntax Example: 
CALL "CVDQ" ADDR(X) 
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CVQD Subroutine 


General Format: 


CALL “CVQD” ADDR (floatdec_variable) 


The CVQD subroutine converts the value of an input variable from 
the float decimal to the float binary representation. The CVQD 
subroutine is useful for cases where a module compiled with float 
decimal numerics must pass float values to or share a common float 
variable with a module compiled with float binary numerics. 


CVQD returns the float binary value to the input variable, 
destroying the previous contents of the variable. The entire range 
of float decimal values can be converted to float binary values. 
The input variable must be in the float decimal format; if the user 
passes a float binary value to CVQD, either an incorrect float 
binary value is returned or processing terminates with a run time 
DMS data exception. 


CVQD is an external subroutine, and must be called with the ADDR 
form of the CALL statement (refer to Subsection 6.5.4 for details). 
In addition, programs calling CVQD must link to the System Library 
(@SYSTEM@) on the System Volume. Consult the VS Program Development 
Tools for details on the LINKER utility. 


NOTE 


The CVQD subroutine cannot be used on VS-80 or VS-50 


systems, since these systems do not support float decimal 
numerics. 


Syntax Example: 
CALL "CVQD" ADDR(X) 
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DATA Statement 


General Format: 


DATA constant ’ constant 
literal literal 


The DATA statement provides the values to be assigned to the 
variables in a READ statement. The READ and DATA statements allow 
tables of constants to be stored within a program. 


Each time a READ statement is executed in a program, the next 
sequential value(s) listed in the DATA statements is obtained and 
stored in the receivers listed in the READ statement. The values 
entered with the DATA statement must be in the order in which they 
are to be used, and separated by commas. If several DATA statements 
occur in a program, they are used in order of statement number. 
Numeric variables in READ statements must reference numeric values; 
alphanumeric receivers must reference literals. 


The RESTORE statement resets the current DATA statement pointer 
so that DATA statement values are reused (see RESTORE). 


Example: 

100 FOR I=1 TO 5 

200 READ W 

300 PRINT W,W**2 

400 NEXT I 

500 DATA 5, 8.26, 14.8, -687, 22 

Output: 5 25 
8.26 68.2276 
14.8 219.04 
-687 471969 
22 484 


In the above example, the five values listed in the DATA 
statement are sequentially used by the READ statement and printed. 
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DATE Function 


General Format: 


DATE 


DATE returns a 6-character string that gives the current date in 
the form YYMMDD. The DATE function takes no arguments. 


Example: 
100 A$=DATE 


200 PRINT STR(A$,3,2);"/";STR(A$,5,2);"/";STR(A$,1,2) 
300 PRINT STR(DATE,3,2);"/";STR(DATE,5,2);"/";STR(DATE1,2) 


Output: 09/15/82 
09/15/82 
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DEF Statement 


General Format: 


DEF function-namel[%](v) = numeric exp 


where: 
function-name = any sequence of up to 64 letters, digits, 
and underscores, provided that the first 
character is a letter, and the name is not 
a VS BASIC reserved word 


v= thedummy variable, a numeric scalar variable 


If % is present, the function will return an /nteger value. 


The DEF statement is also discussed in Subsection 4.4.2. 


The define statement, DEF, enables the programmer to define a 
Single-valued numeric function within the program. Once defined, 
this function can be used in expressions in any other part of the 
program. The function provides one dummy variable whose value is 
Supplied when the function is referenced. Defined functions can 
reference other defined functions, but recursion is not allowed. 
That is, a function cannot refer to itself, nor can one function 
refer to another function that refers to the first. The following 
program illustrates how DEF is used. 


Example: 


100 X=3 

200 DEF OBFUSCATION(Z) = Z**2-Z 
300 PRINT X + OBFUSCATION(2*X) 
400 END 


Output: 33 


Processing of OBFUSCATION(2*X) in this example proceeds in the 
following order: 


1. The expression specified as the argument of the function 
OBFUSCATION (in this case, 2*X) is evaluated. Here, the 
value of the argument is (2*X=6). 


2. The dummy variable in the function definition (in this case, 


Z in line 200) is temporarily assigned the value of the 
argument (in this case, 6). 
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3. The expression to the right of the equals sign ain the 
function definition (line 200) is evaluated given the 
assignment just performed, and the value is returned to the 
statement that invoked the function. In this case, 
(6T2 - 6)=30 is returned to the PRINT statement (line 400), 
which adds the value of X (3, in this case), and prints the 
result (33). 


A user-defined function can be invoked from anywhere in a program. 
The following restrictions apply to definitions of functions: 
1. A DEF function cannot refer to itself. For example, 
DEF APPLE(MY EYE) = MY EYE + APPLE(MY EYE) 
is illegal. 


2. Two DEF functions cannot refer to each other. For example, 
the following combination of statements is illegal. 


DEF ARTICHOKE(X) = BANANA(X) 
DEF BANANA(X) = ARTICHOKE(X) 


Neither, of the above restrictions is checked for during 
compilation, but both cause endless loops resulting in "stack 
overflow" during execution. 


The dummy scalar variable in the DEF statement can have a name 
identical to that of a variable used elsewhere in the program or in 
other DEF statements; current values of the variables are not 
affected during function evaluation. DEF statements can also use 
other variables, using their current values at calling time. 


Syntax Examples: 


600 DEF JAGUAR(C) = (3*A) — 8*C + LION(2-A) 
700 DEF LION(A) = (3*A) — 9/C 
800 DEF TIGER(C) = LION(C) * JAGUAR(2) 


II-36 


DEF FN' Statement 


General Format: 


a (receiverLreceiver] . . .) 
DEF FN" int { kersienerege \ 


1 to 32 for Program Function key entries 
0 to 255 for internal program references 


The DEF FN' statement has two purposes: 


1. To define a literal to be supplied when a Program Function 
(PF) key is used for keyboard text entry. 


2. To define Program Function key or program entry points for 
subroutines with argument passing capability. 


Keyboard Text Entry Definition 


To be used for keyboard entry, the integer in the DEF FN' 
statement must be from 1 to 32, representing the number of a Program 
Function key (PF key). When the corresponding PF key is pressed 
while execution is halted by an INPUT or STOP statement, the user's 
literal(s) is displayed and becomes part of the currently entered 
text line. 


Each literal can be represented by a character string in quotes, 
a HEX function, or a combination of those elements. 


NOTE 


The Program Function keys can be defined to produce 
characters that do not appear on the keyboard by using 


HEX literals to specify the codes for these characters. 


Syntax Examples: 


100 DEF FN'31 "April is the cruelest month." 
200 DEF FN'02 HEX(94); HEX(22);"Mistah Kurtz — he dead.";HEX(22) 


Pressing PF3l at a STOP or INPUT causes April is the cruelest 
month. to be displayed, while pressing PF2 displays "Mistah Kurtz - 
he dead.", blinking and protected because of the HEX(94). The 
quotation marks are displayed because of the HEX (22) 
specifications. Thus, the DEF FN' statement can be used to display 
characters (such as quotation marks surrounding character values) 
that are not usually displayed. 
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Marked Subroutine Entry Definition 


The DEF FN' statement, followed by an integer and an optional 
receiver list enclosed in parentheses, indicates the beginning of a 
marked subroutine. (See Subsections 6.4.2 and 6.4.3 for a 
discussion of marked subroutines.) The subroutine can be entered 
from the program through a GOSUB' statement or from the keyboard by 
pressing the appropriate Program Function (PF) key while execution 
is halted by an INPUT or STOP statement. If a subroutine is to be 
entered through a GOSUB' statement, the integer in the DEF FN' 
statement can be any integer from 0 to 255. If the subroutine is to 
be entered from a PF key, the integer can be from 1 to 32. When a 
PF key is pressed or a GOSUB' statement is executed, the execution 
of the BASIC program transfers to the DEF FN' statement with an 
integer corresponding to the number of the PF key or the integer in 
the GOSUB' statement (i.e., if PF2 is pressed, execution branches to 
the DEF FN'2 statement). 


When a RETURN statement is encountered in the _ subroutine, 
control passes to the program statement immediately following the 
last executed GOSUB' statement, or back to the INPUT or STOP 
statement if the subroutine was entered by pressing a PF key. 
Repeated subroutine calls executed without RETURN or RETURN CLEAR 
statements can cause memory overflow. (See RETURN and RETURN CLEAR. ) 


The DEF FN' statement can optionally include a receiver list. 
The receivers in the list receive the values of arguments being 
passed to the subroutine. 


In a GOSUB' subroutine call made internally from the program, 
arguments are listed (enclosed in parentheses and separated by 
commas) in the GOSUB' statement. If the number of arguments to be 


passed is not equal to the number of receivers in the list, a 
compilation error results. 


Example: 


100 GOSUB'2 (1.2,3+2 * X, "JOHN") 


200 STOP 
300 DEF FN'2 (A,B(3),C$) 


400 RETURN 


Result: STOP 1.2, 3.24, "JOHN" (now press PF2) 
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When entering a subroutine through a PF key, arguments are 
passed by keying them in, separated by commas, immediately before 
pressing the PF key. (See INPUT and STOP.) If the wrong number or 
type of data is given, the entries are refused, the cursor returns 
to the beginning of the field, and the program waits for further 
operator action. 


The DEF FN' statement need not specify a receiver list. In some 
cases, it may be more convenient if the program requests the user to 
enter data at a keyboard in response to prompts. 


Example: 


100 DEF FN'4 

200 INPUT "“RATE",R 
300 C = 100 * R - 50 
400 PRINT "COST=";C 
500 RETURN 


When a DEF FN' subroutine is executed through keyboard PF keys 
while the system is waiting for data to be entered into an INPUT 
statement or is in STOP mode, the INPUT or STOP statement is 
repeated in its entirety upon return from the subroutine. 


Example: 


100 INPUT "ENTER AMOUNT",A 


200 DEF FN'1 
210 INPUT “ENTER NEW RATE",R 
220 RETURN 


Display: ENTER AMOUNT? 
(Press PF1) 
ENTER NEW RATE? 7.5 
ENTER AMOUNT? 


DEF FN' subroutines can be nested (i.e., they can call other 
subroutines from within a subroutine). A  RETURN-~ statement 
encountered in a nested subroutine returns execution to the 
subroutine that called the nested subroutine. 
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DELETE Statement 


General Format: 


DELETE file-exp 


The DELETE command deletes the last record read, which must have 


been read with the HOLD option. It is only valid for indexed files; 
records in consecutive files cannot be deleted. 


See also the description of the HOLD option under the READ Disk 
File statement. 


Syntax Example: 


100 DELETE #1 
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DIM Statement 


General Format: 
DIM dim-elt [,dim-elt] . . . 


where: 
numeric array name (int1[,int2]) 


dim-elt = < alpha array name (int1[,int2])[int3] 
alpha scalar variable [int3] 


intl = row dimension, 1< =int1 << =32767 
int2 = column dimension, 1 < =int2< =32767 
int3 = string length, 1<=int3 <=256 


The DIM statement reserves space for arrays and sets the length 
for alpha scalars or array variables. (Use of the DIM statement is 
also discussed in Subsection 3.5.2.) The DIM statement must appear 
before any of the dimensioned elements are used. 


If not dimensioned in a DIM statement, the following defaults 
hold: 


1. The string length of alpha scalar or array variables 
defaults to 16. This is also true if int3 is omitted in a 
DIM statement. 


2. Arrays default to 10-by-10 matrices. 


Arrays or variables dimensioned in a COM statement cannot be 
respecified in a DIM. (See the discussion of the COM statement.) A 
variable or array can occur in only one DIM or COM in each program 
or subprogram. 


Arrays can be redimensioned by using [MAT] REDIM. 


Syntax Examples: 


100 DIM A$100 
200 DIM A$(4,4),B$(12,12)20,B(3,7) 
300 DIM A(10),B$(20)10 


Note that in a DIM statement, DIM must be the first word of the 


statement; if DIM is used in any other way, it is interpreted as 
referring to the DIM function. 


II-41 


DIM Function 


General Format: 


DIM (array-designator , { 


where: 
{1} =row dimension 
{2} = column dimension 


The DIM function returns, as an integer value, the current row 
(1) or column (2) dimension of the specified array. The column 
dimension of a vector is 1%. 


NOTE 


The defined length of an alpha scalar or array variable 


can be obtained using LEN(STR(variable)). 


Syntax Examples: 


100 A=DIM(A(),1) 
200 B=DIM(A(),2) 
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DISPLAY Statement 


General Format: 
DISPLAY list List]... 


where: 
COL (int) 
AT (exp2, exp3) 


list = < numeric exp [,PIC (image)] 
alpha-exp [,CH (int)] 
BELL 


image = a valid numeric image, as in FMT 
int =  anint specifying the length of the (alpha) field 


DISPLAY allows output of numeric and alphanumeric data values at 
the workstation in a field-oriented manner, using the supplied 
formatting information. (See Section 7.6 for a detailed 
discussion.) Both single values and arrays can be displayed. 


DISPLAY works in generally the same way as ACCEPT, with the 
following exceptions: 


1. Values are written only; no new values are accepted. (Thus 
there are no PF key clauses or FAC characters. ) 


2. Pseudoblanks are not used. 

Otherwise, see ACCEPT. The screen is cleared prior to DISPLAY, 
and a STOP statement should be used in order to halt execution for 
viewing (if desired) following DISPLAY. 

See Chapter 7 for more information on screen I/O. 

Syntax Examples: 


100 DISPLAY COL(10) ,A$,CH(20) ,AT(20,20) ,A,PIC(##. ##) 
200 DISPLAY B$,BELL 
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EJECT Compiler Directive 


General Format: 


EJECT 


EJECT is a compiler directive (see Subsection 2.4.2). The EJECT 
statement, which must be the only statement on a line, causes the 
compiler to skip to the top of the next page of the source listing 
and print the most recently specified title at the beginning of the 


page. 


Syntax Example: 
100 EJECT 
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END Statement 


General Format: 


END [exp] 


This statement is required to terminate the program prior to its 
physical end or to pass a program-supplied return code to the 
operating system. It can be used anywhere and any number of times 
in the program. It is not required at the physical end of the 
program where an implied END is automatically generated. 


When the END statement is encountered, program execution 
terminates or, if in a subroutine, returns to the calling program. 
If END is followed by an expression, the value of the expression 
(truncated if not an integer) is passed to the operating system as a 
return code. If the expression is omitted, the return code is 0. 


Syntax Examples: 


100 END 
999 END A 


The second example passes the current (truncated) value of A to the 
system as a return code. Return codes are often useful in writing 


procedures. (See the VS Procedure Language Reference for a 
discussion of procedures and the use of return codes. ) 
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EXP Function 


General Format: 


EXP (numeric exp) 


The EXP (exponential) function returns a floating-point value 
equal to the natural constant "e" (the base of natural logarithms; e 
is approximately equal to 2.71828182845904) raised to the power 
given by the value of the argument. EXP is the inverse function of 
LOG. 


Example: 
100 A = EXP(1) 
200 B = EXP(73) 


300 PRINT A, B 


Result: 2.718281828 9744803446 


IT-46 


FMT Statement 


General Format: 
FMT form-spec [,form-spec] . .. 


where: 
{rep-int *Jdata-spec 


form-spec = [rep-int *lliteral 
control-spec 


rep-int = integer specifying the number of times to 
repeat the data-spec or literal 


FMT is a nonexecutable statement used to format data values for 
PRINT and disk I/O statements. (See Sections 7.4 and 8.4 for 
discussions of the use of the FMT statement.) The FMT statement and 
the FORM statement are synonymous and can be used interchangeably. 
They can be used wherever Image(%) is allowed, subject to the 
following restrictions: 


1. BI, FL, and PD are not displayable formats, and thus are 
legal only for disk I/O statements. 


2. For PRINTUSING, the FMT statement can be reused for long 
argument lists. This is exactly like Image (%), and is 
described in the PRINTUSING section. 


A control specification (control-spec) is one of the following 
items. 


1. XX [(int)] -- Skip int positions (input) or write n blanks 
(output). If omitted, int=1. 


2. COL (int) or POS (int) -- Next form-spec to start at 
position int in record or output line. (For disk I/O, 
int <= record size. For PRINTUSING, COL>80 or current 
printer width causes the next form-spec to begin at column 1 
of the next line.) 


3. TAB (int) -— Like COL, but all skipped-over characters are 
set to blank. 


4. SKIP [(int)] -- Skip int lines (default=1). Like PRINT SKIP. 
(Not for disk I/O.) 
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A data specification (data-spec) is one of the following items. 
Note that w and d are integer constants. 


1. CH(w) -—- Character data, w bytes. 


2. BI{(w)] -- Binary internal format, w _ bytes. 1<=w<=4, 
default=4. 

3. FL[(w)] -- Floating-point internal format, w bytes w=4 or 8, 
default=8. 

4. PD(w[,d]) -- VS packed decimal, w digits, d digits to the 


right of the (implied) decimal point (default d=0). Number 
of bytes required is 1+INT(w/2). 


# + + 
0 0 7 
5. PIC({+]{$] * * 1... [TTT] ++ ) 
B B —— 
/ / 
Editing Characters 
+ Digit position -— blank if leading zero. 


Decimal point. 


TTtT Exponent E+xx for exponential output. If present, the 
digit positions are filled with significant digits (no 
leading zeros) and the exponent is scaled accordingly. 


* Replace leading 0 with *. 

0 Retain leading 0. 

j If right of a numeric digit, insert ',' ; otherwise, 
blank. 

/ If right of a numeric digit, insert '/' ; otherwise, 
blank. 

B Insert blank. 
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Sign Trailing + '+' > 0, '-' if < 0 
- blank if > 0, '-' if < 0 
++ 2 blanks if > 0, 'CR' if < 0 
--~ 2 blanks if > 0, 'DB' if < 0 


NOTE 


A leading sign and a trailing sign cannot both be 


specified. If no signs are present, the absolute value 
of the number is printed. 


Sign Leading + '+' if > 0, '-' 1f£ ¢< 0 
- blank if > 0, '-' if < 0 
$ '$' precedes the number 


(The above three characters float to the leftmost nonzero 


digit location. ) 


Syntax Examples: 


100 FMT PIC(##.##TTTT) 
200 FMT SKIP(10),CH(50) ,SKIP(—-5) ,COL(20) ,PIC($**. ++) 


NOTE 


The FMT Statement always extends to the end of the line 


on which it occurs. It cannot be terminated by use of a 
colon (:), as described in Section 2.3.2. 
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FOR Statement 


General Format: 


FOR numeric scalar variable = exp1 TO exp2 [STEP exp] 


The FOR and NEXT statements specify a loop. The FOR statement 
marks the beginning of the loop and defines the loop parameters. 
The NEXT statement marks the end of the loop. The program lines in 
the range of the FOR statement are executed repeatedly, beginning 
with variable = expl. The variable value is incremented by the STEP 
expression value until it exceeds the value of exp2. 


The three expressions can take on any value. If STEP is 
omitted, 1 is assumed. STEP and exp2 are evaluated only once; if 
STEP is 0 or has the wrong sign, the loop is executed only once. 


After termination of the loop, the variable has the last value 
used, i.e., without the final increment. There are no restrictions 
on branching in or out of the loop, provided that a NEXT without an 
open FOR is not encountered; this event causes an error. 


NOTE 


If the loop variable is an integer variable, expl, exp2 


and the step exp are truncated to integers and all loop 
calculations are integer type. 


Example: 
100 FOR A=1 TO 10 STEP 3 
200 PRINT A 
300 NEXT A 
Result: 
1 
4 
7 


10 
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FORM Statement 


General Format: 


FORM form-spec [ ,form-spec }... 


where: 


[rep-int*]data-spec 
form-spec = < [rep-int*Jliteral 


control-spec 


rep-int = integer specifying the number of times to 
repeat the data-spec or literal 


Synonymous with FMT. 
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FS Function 


General Format: 


FS (file-exp) 


The FS function returns the file status for the most recent I/0 
operation on the specified file. The returned file status value is 
an alphanumeric value two characters long. FS can assume any of the 
following values: 


CONSEC, TAPE, and PRINTER File I/0 


'00' Successful I/O operation 

'10' End-of-—file encountered 

a3" Invalid record number 

'30' Hardware error 

'34' No more room in the file 

"95! Invalid function or function sequence 
aT? Invalid record length 


INDEXED File I/O 


‘00' Successful I/O operation 

'10' End-of—file encountered 

'21' Key out of sequence (WRITE statement in OUTPUT mode only) 

'22' Duplicate key 

‘23° No record found matching specified key 

"24! Supplied key exceeds any key in the file (INPUT, IO, or 
SHARED mode) 

'30' Hardware error 

'34' No more room in the file (OUTPUT or IO mode) 

"95! Invalid function or function sequence 

'97' Invalid record length 


SHARED Mode I/O Errors (not normally encountered by the BASIC user) 


"80' Invalid Key area (START, READ KEYED) 
'8l' Invalid READ NODATA 

"82" Label update error 

"83! Sharing task was terminated 

"84! Invalid record size/record area 


(Record size > 2048) 


Syntax Example: 
100 Y$ = FS(#1) 
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GET Statement 


General Format: 


file-exp line number 
oen eee E = eee label \ arg Larg]... 


GOTO line number 
|oara cn on ‘oa 


where: 


_ ) receiver 
ao'= mee, 


GET allows extraction of data from the record area in a file or 
from an alpha-expression USING the referenced Image (%) or FMT 
statement, or using standard format. Data in the record area 
referenced by the file-expression are those read with the last READ 
statement; these data are available to GET until they are 
overwritten by another READ from the same file, or by a PUT, WRITE, 
or REWRITE for that file. 


The DATA exit is taken if data conversion fails (e.g., character 


string moved to numeric variable, alpha-expression too short to fill 
all the arguments, etc.). 


Syntax Examples: 


100 GET #A USING 300,B,DATA GOTO 500 
300 FMT PIC(+##+) 


NOTE 


GET can be used to convert numeric data from internal 
formats used by COBOL programs to BASIC numeric data 


format. See Appendix C for information on numeric data 
compatibility between BASIC and COBOL. 
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‘'GOSUB Statement 


General Format: 


line number 
GOSUB fretiae label \ 


The GOSUB statement is used to transfer program execution to the 
first program line of a subroutine. (The use of the GOSUB statement 
is discussed in Subsection 6.4.1.) The program line can be any 
BASIC statement, including a REM statement or a statement label 
line. The logical end of the subroutine is a RETURN or RETURN 
CLEAR statement. A RETURN statement directs execution to _ the 
statement following the last executed GOSUB; a RETURN CLEAR 
statement clears the subroutine information but causes no branch. 


The GOSUB statement can be used to perform a subroutine within a 
subroutine; this technique is called "nesting" of subroutines. 


Subroutines should not be entered repeatedly without executing a 
RETURN or RETURN CLEAR. Failure to execute a RETURN or RETURN CLEAR 
causes return information to accumulate in a table, which can 
eventually cause a memory stack overflow error. 


Example: 


120 X = 20:GOSUB 200:PRINT X 
125 
130 GOSUB TEST 


190 TEST: 
200 REM SUBROUTINE BEGINS 


210 RETURN: REM SUBROUTINE ENDS 
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GOSUB' Statement 


General Format: 


GOSUB’intl(argl,arg] .. .)] 


where: 
O<=int< =255 


_ J exp 
arg ee 


The GOSUB' statement specifies a transfer to a marked subroutine 
rather than to a particular program line, as does the GOSUB 
statement. (The use of the GOSUB' statement is discussed in 
Subsection 6.4.2.) A subroutine is marked by a DEF FN' statement. 
When a GOSUB' statement is executed, program execution transfers to 
the DEF FN' statement having an integer identical to that of the 
GOSUB' statement (i.e., GOSUB'6 transfers execution to the DEF FN'6 
statement). Subroutine execution continues until a = subroutine 
RETURN or RETURN CLEAR statement is executed. The rules applying to 
GOSUB also apply to the GOSUB' statement. Unlike a normal GOSUB, 
however, a GOSUB' statement can contain arguments whose values can 
be passed to variables in the marked subroutine. 


The values of the expressions, literal strings, or alphanumeric 
variables are passed to the variables in the DEF FN' statement left 
to right. Elements of arrays must be explicitly referenced (i.e., 
they cannot be referenced by the array-designator or array name 
alone). The arguments of the GOSUB' must be passed to variables of 
the same type (i.e., alpha expressions must be passed to alpha 
variables, and numeric expressions must be passed to numeric 
variables). 


Subroutines should not be entered repeatedly without executing a 
RETURN or RETURN CLEAR. Failure to execute a RETURN or RETURN CLEAR 
causes return information to accumulate in a table, which can 
eventually cause a stack overflow error. 


Examples: 


100 GOSUB'7 

150 END 

200 DEF FN'7:SELECT PRINTER (80) 
210 RETURN 


100 GOSUB'12 ("JOHN",12.4,3*X+Y) 
200 END 

300 DEF FN'12(A$,B,C(2)) 

400 PRINT A$,B,C(2) 

500 RETURN 
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GOTO Statement 


General Format: 


GOTO 


line number 
statement label 


This statement transfers execution to the specified line number 


or statement label; 


statement. 


Example: 


100 
200 
300 
400 
500 
600 
650 
700 
800 
900 


J=25 

K=15 

GOTO TEST 
Z=J+K+L+M 
PRINT Z,Z/4 
END 

TEST 

L=80 

M=16 

GOTO 400 


Output: 136 34 


execution continues 
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at the 


specified line 


HEX Function 


General Format: 


HEX(hh[hh] . . .) 


where: 
h = hexdigit (O to 9 or A to F) 


The hexadecimal function, HEX, is a form of literal string that 
enables any 8-bit code to be used in a BASIC program. Each 
character in the literal string is represented by two hexadecimal 
digits. If the HEX function contains an odd number of hexdigits or 
if it contains any characters other than hexdigits, an error results. 


Syntax Examples: 


100 A$=HEX(OCOAOA) 
200 IF A$ > HEX(7F) THEN 100 
300 PRINT HEX(8001);"TITLE" 
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HEXPACK Statement 


General Format: 
HEXPACK alpha-receiver FROM alpha-exp java es a ates number y 


GOSU statement label 


The HEXPACK statement converts an ASCII character string that 
represents a string of hexadecimal digits into the binary equivalent 
of those hexadecimal digits. Hexadecimal digits entered from the 
keyboard can be entered as ASCII characters; they can then be 
converted from ASCII code to their true binary equivalent with 
HEXPACK. For example, the hexadecimal digit A has a binary value of 
1010. However, this digit is represented by an ASCII character A, 
which has a binary value of 01000001. The HEXPACK statement can be 
used to convert the binary value of ASCII character A into the 
binary value of the hexadecimal digit A, and to store this value in 
the specified alpha-receiver. 


The alpha-expression (actual length) contains the ASCII 
character string that represents a string of hexadecimal digits. 
Each pair of ASCII characters is converted to 1 byte of the 
corresponding binary’ value. Only certain ASCII characters 
constitute legal representations of hexadecimal digits. These 
include the characters 0 through 9 and A through F, as well as the 
special characters :, ;, <, =, >», and ?. These characters are 
converted to the following binary values: 


ASCII Character Binary Value 


0000 
0001 
0010 
0011 
0100 
0101 
0110 
0111 
000 

1001 
1010 
1011 
1100 
1101 
1110 
1111 


WOONAUW PWN EO 


or 
or 
or 
or 
or 
or 


YHOO Ww YP 
IV i] AN ve ee 


If the alpha-expression contains any characters other than those 
listed above, including embedded spaces (i.e., any character that is 
not a legal representation in ASCII of a hexadecimal digit), an 
error occurs; if the DATA exit is specified, it is taken. 
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If the alpha-expression contains an odd number of legal 
hexadecimal digits, it is padded on the right with one hex zero. 


The alpha-receiver receives the converted binary value. Since 
each pair of characters in the value of the alpha-expression is 
converted to a 1-byte binary value in the alpha-receiver, the 
alpha-receiver should have at least half as many bytes (defined 
length) as the alpha-expression. If the alpha-receiver is too short 
to contain the entire converted binary value, an error occurs and 
program execution halts. If the alpha-receiver is longer than the 
converted binary value, the binary value is left-justified, and the 
remaining bytes of the alpha-receiver are not modified. 


Example 1: 


100 DIM P$2, U$4 é 

200 INPUT "VALUE TO BE PACKED" ,U$ 
300 HEXPACK P$ FROM U$ 

400 PRINT HEXOF (P$) 


Output: 
VALUE TO BE PACKED?12C9 


12C9 


The availability of the special characters ":" (HEX (3A)) through 
"2" (HEX (3F)) to represent hexadecimal digits A through F (1010 
through 1111) means that HEXPACK will recognize any ASCII code with 
a high-order 3 digit (hexadecimal 30 through hexadecimal 3F) as a 
legitimate representation of a hexadecimal digit. This fact makes 
it easy to transform any code into an acceptable representation of a 
hexadecimal digit, and hence to perform operations such as packing 
the low-order digits (low-order four bits) from a= string of 
hexadecimal digits. The technique is illustrated in Example 2. 


Example 2: 


100 DIM P$2, V$4 

200 V$ = HEX (01020C09) 
300 V$ = OR ALL (HEX(30)) 
400 HEXPACK P$ FROM V$ 
500 PRINT HEXOF(P$) 


Output: 12C9 
Syntax Examples: 


HEXPACK A$ FROM BS 

HEXPACK STR(A$,1,3) FROM STR(B$,7) 
HEXPACK A$() FROM B$() 

HEXPACK A$ FROM "3AFC282C" 
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HEXPRINT Statement 


General! Format: 


alpha variable : alpha variable 
HEXEN ee array aes} t : \ fe array designator 


This statement prints the value of the alpha variable or the 
values of the alpha array in hexadecimal notation. The printing or 
display is done on the device currently selected for PRINT 
operations (see SELECT). The defined lengths of the alpha values 
are printed. Arrays are printed one element after another with no 
separation characters. A new line is started after the value(s) of 
each alpha variable (or array) in the argument list, unless the 
argument is followed by a semicolon. If the printed value of the 
argument exceeds one line on the workstation or printer, it 
continues on the next line or lines. Since the carriage width for 
PRINT operations can be set to any width by the SELECT statement, 
this can be used to format the output from long arguments. 


Note that HEXPRINT X$, Y$, Z$ is the same as PRINT HEXOF (X$), 
HEXOF (Y$), HEXOF (Z$). 


Syntax Example: 


100 HEXPRINT A$ 
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HEXUNPACK Statement 


General Format: 


HEXUNPACK alpha-exp TO alpha-receiver 


The HEXUNPACK statement converts the binary value of an 
alpha-expression (defined length) to a string of ASCII characters 
representing the hexadecimal equivalent of that value. The 
resulting characters are stored in the alpha-receiver. 


HEXUNPACK is the logical inverse of HEXPACK, except’ that 
characters 3A through 3F are not used; the characters produced are 
in the range 0 through 9 and A through F. 


If the alpha-receiver is not at least twice as long as the 
alpha-expression (defined length), an error occurs. If it is 
longer, the result is left-justified and unused characters remain 
unchanged (as with HEXPACK). 


Example: 


100 DIM P$2, US4 

200 P$ = HEX (12C9) 
300 HEXUNPACK P$ TO U$ 
400 PRINT US$ 


Output: 12C9 


syntax Examples: 


HEXUNPACK A$ TO B$ 
HEXUNPACK STR(A$, 5) TO STR(BS, 1, 4) 
HEXUNPACK A$() TO B$() 
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IF...THEN...ELSE Statement 


General Format: 


line number line number 
executable executable 

IF relation THEN < statement* statement* 
statement statement 
label label 


*except another IF 


alpha exp operator alpha exp 


numeric exp operator numeric exp 


AND 
relation = relation OR relation 


XOR 


NOT relation 
(relation) 


operator = 


AVA 
ivi yva 


The IF statement causes conditional transfer or statement 
execution. Depending on the value of the relation, execution 
continues as follows. 


1. Relation true: 

a. If "THEN line number (or statement label)" is specified, 
execution continues at the specified line number or 
statement label. 

b. If "THEN executable statement" is specified, the 
statement is executed. Program execution then continues 


at the next executable statement. 


c. In either case, the ELSE clause is ignored. 
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2. Relation false: 


a. If the ELSE clause is not specified, execution continues 
at the next executable statement. 


b. If the ELSE clause is specified, it is used like THEN in 
1 and 2 above. 


c. In either case, the THEN clause is ignored. 


Two expressions are compared using standard numerical order; 
integers are converted to floating-point before being compared with 
floating-point values. Two alpha-expressions are compared using 
their ASCII hexadecimal codes, with the shorter expression 
right-—padded with blanks (HEX(20)). 


Complex IF statements containing character relation expressions 
of the form "IF A AND B AND C AND D THEN XYZ" can in some cases 
cause program checks or random branches. It is recommended that 
such complex relations be written in two separate statements. 


The hierarchy of execution of the relational expression is as 
follows: 


Parentheses 

<5 <3) hy PS Se SS 

NOT 

AND, OR, XOR 
Left-to-right execution 


WO Bm WN FH 


NOTE 


Nested IF statements are not allowed. 


Syntax Examples: 


100 IF A > .5 THEN 1000 

200 IF A$>B$ AND B$>C$ THEN B=5 ELSE B=0 

300 IF NOT A=B THEN 1000 . 

400 IF E$<=F$ AND (NOT N>I) THEN 1000 ELSE 800 
500 IF A>B THEN TEST ELSE NO TEST 
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Image (%) Statement 


General Format: 
% character string 
format spec 


where: any character 
character string = eee # \ 


+ 
‘ovmabapec= {x} $]#... Ub... U0... | 
++ 


The Image (%) statement is a nonexecutable statement that 
formats output from PRINTUSING, disk I/O and GET and PUT 
statements. One format specification is used for each numeric or 
alpha value, left to right. 


For alphanumeric values, the format specification is filled from 
left to right, regardless of the editing characters. The output 
value is right-padded with blanks or truncated to fit the format 
specification. 


For numeric values, the editing characters in the format 
specification are interpreted depending upon the value to be 
formatted. 


Format Characters 


Leading: + '+' if > 0, '-' if < 0 
_ blank if > 0, '-' if < 0 
$ '$' precedes the number 


(The above three characters float to just before the leftmost 
nonzero digit location.) 


+ digit position —- blank if leading zero. 
decimal point. 


, comma if at least 1 significant digit is positioned to 
the immediate left; otherwise blank. 


TET exponent E+xx for exponential output. If present, the 


digit positions are filled with significant digits (no 
leading zeros) and the exponent is scaled accordingly. 
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Trailing: + ‘+' if >0, '-' if <0 


- blank if >0, '-' if <0 
++ 2 blanks if >0, 'CR' if <0 
-- 2 blanks if >0,'DB' if <0 


NOTE 


If a leading sign is present, the trailing sign 
is ignored. That is, it becomes part of the 
next character string. 


If no signs are present, the absolute value of 
the number is printed. 


There must be at least a single # in a format specification, 
and the output field width is always the same length as the 
format specification, whether the output is numeric or 
alphanumeric. 


For numeric output: 
a. Fractions are truncated. 


b. If the format is insufficient for the integer part of 
the number, the format specification itself is output, 
with the correct leading sign, if the leading sign 
character is present. 


If all format specifications are not used, everything up to 
the first unused format is used, including a final character 
string. 


A trailing character string in an Image (%) statement is 
considered to extend to the last nonblank character. 


Continuation characters are illegal in the format clause; 
the format clause is considered at an end if an ! is 
encountered. 


Syntax Examples: 


100 


100 
200 
300 
400 
500 


4“4FEAR IN A HANDFUL OF DUST +44+#, #4, 4+. #4 


ACCEPT A,B,C 

PRINTUSING 300, A,B,C 
hae , HHH. HHE++ GHEE. HHE-— HHH HET TTT 
STOP 

GOTO 100 
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INIT Statement 


General Format: 


INIT (alpha-exp) alpha-receiver [,alpha-receiver] . .. 


The INIT statement initializes the specified alphanumeric 
receivers. Each character in the defined length of _ the 
alpha-receiver(s) is set equal to the first character of the 
alpha-expression. For arrays, each character of each element of the 
array is set to the first character of the alpha-expression. 


Example: 


100 DIM A$5, M$(5)3 
200 INIT("?") AS, M$() 


Result: A$ = "27222" 
M$(1) = "222" 
M$(2) = "222" 
M$(3) = "222" 
M$(4) = "222" 
M$(5) = "222" 
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INPUT Statement 


General Format: 


INPUT [literal,] receiver [receiver]... 


This statement allows the user to supply data during the 
execution of a program. If the user wants to supply the values for 
A and B while running the program, a statement such as 


400 INPUT A,B 
or 
400 INPUT "VALUE OF A,B",A,B 


must be entered before the first program line that requires either 
of these values (A,B). When the system encounters this INPUT 
statement, it prints the message VALUE OF A,B, followed by a 
question mark (7), and waits for the user to supply the two 
numbers. Once the values are _ supplied, program execution 
continues. The program assigns values left to right, one at a 
time. The device used for entering data is the workstation. 


Each value must be entered in the order in which it is listed in 
the INPUT statement, and values entered must be compatible with 
receivers in the INPUT statement. If several values are entered, 
they must be separated by commas or entered on separate lines. As 
many lines as necessary may be used to enter the required INPUT 
data. To include commas or leading blanks as part of an alpha 
value, enclose the value in double or single quotes (" or '), for 
example, “BOSTON, MASS.". 


Variables in the INPUT list that the user does not wish to 
change can be skipped over by entering a null value, i.e., a comma 
not immediately preceded by a data item. For example, 


Program: VALUE OF A,B,C,D? 
User: 4.3,2.0,,3.5 


Result: Variable C will not be changed; A,B, and D get new 
values. 


A user can terminate an input sequence without supplying any 
additional input values by simply keying ENTER with no other 
information preceding it on the line. This causes the program to 
immediately proceed to the next program statement. The INPUT list 
receivers that have not received values remain unchanged. 


When entering alphanumeric data, literal strings need not be 
enclosed in quotes. However, leading blanks are ignored and commas 
act as string terminators. (This also applies to _ subroutine 
parameters; see Subsection 7.5.3.) 
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Example 1: 
100 INPUT X 


Output: ?12.2 (ENTER) 
(underlined portion supplied by user) 


Example 2: 


200 INPUT "MORE INFORMATION" ,A$ 
300 IF A$="NO" THEN END 

400 INPUT "ADDRESS" ,B$ 

500 GOTO 200 


Output: MORE INFORMATION? YES (ENTER) 
ADDRESS? BOSTON, MASS (ENTER) 
MORE INFORMATION? NO (ENTER) 


Program Function Keys in Input Mode 


Program Function (PF) keys can be used in conjunction with 
INPUT. If the PF key has been defined for text entry (see DEF FN') 
and an INPUT statement is executed, pressing the PF key causes the 
character string in the DEF FN' statement to be displayed on the 
CRT. The displayed value is stored in the variable that occurs in 
the INPUT statement when the ENTER key is pressed. For example: 


100 DEF FN'01"COLOR T.V." 
200 INPUT A$ 


Result: ? 
(Now, pressing PFl causes "COLOR T.V." to appear on the CRT.) 


?COLOR T.V._ 
(CRT Cursor) 


If the PF key is defined to call a marked subroutine (see DEF 
FN') and the system is awaiting input, pressing the PF key causes 
the specified subroutine to be executed. No assignment occurs, and 
the values entered before pressing the PF key are ignored, unless 
the subroutine has an argument list. If so, as many values as are 
required are taken, starting from the leftmost value keyed; those 
left over are ignored. The workstation alarm sounds if there are 
too few values or if those values do not correspond correctly to the 
receivers in the GOSUB' argument list. An illegal PF key also 
causes an alarm. When the RETURN statement is encountered, control 
returns to the INPUT statement and the INPUT statement is executed 
again. Subroutines should not be entered repeatedly through PF 
keys unless a RETURN or RETURN CLEAR statement is. executed. 
Otherwise, return information accumulates in a table and can 
eventually cause a stack overflow error. 
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Example: 


PF2 


The program below enters and stores a series of numbers. 
is pressed, they are totalled and printed. 


100 
200 
300 
400 
500 
600 
700 
800 
900 


DIM A(30) 

N=1 

INPUT "AMOUNT" ,A(N) 
N=N+1:GOTO 300 
DEFFN ' 02 

T=0 

FOR I=1 TON 
T=T+A(I) 

NEXT I 


1000 PRINT "TOTAL=";T 
1100 N=1 
1200 RETURN 


Output: AMOUNT? 7 (ENTER) 


AMOUNT? 5 (ENTER) 
AMOUNT? 11 (ENTER) 
AMOUNT? (Press PF2) 
TOTAL = 23 

AMOUNT ? 
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When 


INT Function 


General Format: 


INT (numeric exp) 


The INT (integer) function returns an integer value that is the 
greatest integer less than or equal to the value of the numeric 
expression specified as the argument. 


Numeric Examples: 


INT( 1.5) 
INT(~1.5) 


1 
=Z 


Syntax Example: 
100 Y% = INT(4.5) 
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KEY Function 


General Format: 


KEY (file-exp [,exp]) 


KEY returns the primary key (or an alternate key) of the last 
record read from the specified file. If exp is 0 or omitted, the 
primary key is returned. Otherwise, the alternate key with key 
number = exp (from SELECT) is returned. (For alternate-indexed files 
only.) 


The length of the result is the (primary or alternate) key length 
as specified in SELECT. 


KEY can also be used as a receiver to set the (primary or 
alternate) key field in the record prior to WRITE or REWRITE. 


Syntax Example: 


100 Y = KEY(#1) 
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LEN Function 


General Format: 


LEN (alpha-exp) 


LEN determines the actual length, in bytes, of the 
alpha-expression. It can be used wherever a numeric expression is 
permitted. The result of LEN is an integer value. 


Example: 


100 A$ = "ABCD" 
200 PRINT LEN (A$) 


These program lines print the value 4 at execution time. 


Example: 
300 X = LEN(AS$) +2 


Combined with lines 100 and 200 above, this line assigns the value 6 
to X at execution time. 


Example: 


100 A$ = "ABCD" 
200 PRINT LEN(STR(A$,2)) 


These lines give the value 15 at execution time. Since A$ is not 
explicitly dimensioned, the default value for its length is 16 
bytes. The STR function extracts the bytes from A$, starting at the 
second byte, to its end. The length of such a value is 15. 


Example: 


100 DIM A$64 
200 A$ = "ABCD" 
300 PRINT LEN(STR(A$,POS (A$=HEX(20)))) 


These lines give the value 60 at execution time. The length of the 
alpha scalar is initially 64; the value of the POS function is first 
determined, giving the position of the first blank character in A$ 
equal to 5. The STR function then extracts the number of bytes from 
the first blank character to the end of the scalar. 
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LET Statement 


General Format: 
[LET] numeric variable [,numeric variable] .. . = numeric exp 


or 


[LET] alpha-receiver [,alpha-receiver] ... = alpha-exp 


or 


[LET] alpha-receiver = logical exp 


The LET statement evaluates the expression following the equal 
Sign and assigns the result to the receiver(s) specified preceding 
the equals sign. If more than one receiver appears before the 
equals sign, they must be separated by commas. If the right-hand 
side of the statement is a logical expression (see Section 5.7), 
only one receiver can appear on the left. 


An error results if a numeric value is assigned to an 
alphanumeric receiver, or if an alphanumeric value is assigned to a 
numeric variable. 


Examples: 
400 LET X(3),Z,Y=P+15/2+SIN(P-2.0) 
500 LET J=3 
In the following example, LET is assumed. 
100 X=A*E-Z*Y 
200 A$=B$ 
300 C$,D$(2)="ABCDE" 


The following routine produces the indicated output at execution 
time: 


100 C$ = 'ABCDE' 
200 A$ = "123456" 
300 D$ = STR(A$,2) 
400 E$ = HEX(41) 
500 PRINT A$,C$,D$,ES 
Output: 
123456 ABCDE 23456 A 
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The execution of 

[LET] recl, rec2,..., recn = value 
1s equivalent to 

{LET] recn = value 


[LET] recn-l = value 


-LET] recl = value 


for both alpha and numeric assignment. Assignment is right to left. 


II-74 


LGT Function 


General Format: 


LGT (numeric exp) 


The LGT function returns a floating-point value equal to the 
common (base 10) logarithm of the numeric expression specified as 
the argument. 


Syntax Example: 
100 X = LGT(100) 


Numeric Example: 
LGT (100) = 2 
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LOG Function 


General Format: 


LOG (numeric exp) 


The LOG function returns a floating-point value equal to the 
natural logarithm (base "e") of the argument. LOG is the inverse 
function of EXP. 


Syntax Example: 
100 X = LOG(2) 


Numeric Example: 
LOG (10) = 2.30258509299404 
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MASK Function 


General Format: 


MASK (file-exp) 


MASK returns :the alternate key access mask (alternate indexed 
file) for the last record read from the specified file. The result 
is a 2-byte (16-bit) alphanumeric value whose bits (left to right) 
correspond to available alternate keys (1 through 16). Bits that 
are "on" (binary 1) specify that the record can be accessed, through 
a READ statement with a key clause, by those alternate key paths. 


The MASK function can also be used as a receiver to set the 


alternate key mask for a record prior to a WRITE or REWRITE 
statement. 


Syntax Examples: 


100 A$=MASK (#1) 
200 MASK (#2 )=HEX(FFOO) 


II-77 


MAT + (MAT Addition) Statement 


General Format: 


MAT c=a+b 


where: 
C, a, and b are numeric array names 


This statement adds two matrices or vectors of the same 
dimension. The sum is stored in array c. Any two or all of a, b, 
and c may be the same array. Array c is implicitly redimensioned to 
have the same dimensions as arrays a and b. 


An error occurs and execution is terminated if the dimensions of 
a and b are not the same. 


Example 1: 


100 DIM A(5,5),D(5,5),E(7),F(5),G(5) 
200 MAT A=A+D 
300 MAT E=F+G 
400 MAT A=A+A 


Example 2: 


This program adds the corresponding elements of the 
three-by-three arrays D and E, to give the new array F. Array F is 
automatically redimensioned as a three-by-three array. 


100 DIM D(3,3),E(3,3),F(5,2) 

200 PRINT "ENTER ELEMENTS OF ARRAY D" 
300 MAT INPUT D 

400 PRINT "ENTER ELEMENTS OF ARRAY E" 
500 MAT INPUT E 

600 MAT F=D+E 

700 PRINT "ELEMENTS OF ARRAY F"': PRINT 
800 MAT PRINT F; 


"1 1 1' "3 3 3' 
Let D= ee 1 1' E= ‘3 3 3" 
"2 2 2' "3 3 3' 


When the program is executed, array F is displayed: 


ELEMENTS OF ARRAY F 


4 4 4 
4 4 4 
5 5 5 
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“MAT. ASORT/DSORT Statement 


General Format: 


M numeric array name -_ JASORT (numeric array name2) 
AT alpha array name1 DSORT ( ) (alpha array name2) 


Array 2 is sorted in ascending (ASORT) or descending (DSORT) 
order into array 1. Array 1 is redimensioned to correspond to array 
2 as follows: 


Array 2 Array 1 Redimensioned to 
(nxm) (L] (pxq) [k] (nxm) [L] 
(nxm) [L] (p) [k] (nmx1) (L) 
(n)[L] (pxq) [k] (nx1)(L] 
(n)[L] (p) [k] (nx1)[L] 


where n,p= number of rows; 
m,q= number of columns. 


An error occurs if array 1 is not as large (in bytes) as array 2. 
. The sorted values are placed in array 1 row by row, starting 
with the first array variable. If array 1 is larger than array 2, 
the remaining locations are unchanged. 

As sorting is done directly into array 1, the two arrays cannot 


be the same (1.e., sort-in-place is not supported). | 


NOTE 


Alphanumeric sorting uses the usual ASCII collating 


sequence. 


Syntax Examples: 


100 MAT A=ASORT(B) 
200 MAT A$=DSORT (B$) 
300 MAT C$=ASORT (B$) 
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Program Example: 


100 DIM A(3,4),B(2,3),C(7) 
200 MAT READ(B) 

300 MAT A=ASORT(B) 

400 MAT C=DSORT(B) 

500 MAT PRINT B,A,C 

600 DATA 3,4,7,1,5,2 


Result: 
B 3 
1 
A 1 
4 
7 
5 
C 4 
3 
2 
1 
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MAT CON (MAT Constant) Statement 


General Format: 


MAT c=CON [(d1[,d2))] 


where: 
c = numeric array name 
d1,d2 = expressions specifying new dimensions 
1<=d1,d2<=32767 


This statement sets all elements of the specified array to l. 
Using (dl1,d2) causes the matrix to be redimensioned. If (dl,d2) is 
not used, the matrix dimensions are as specified in a previous COM, 


DIM, or MAT statement, or are the default values. 


Syntax Examples: 


100 MAT A=CON(10) 
200 MAT C=CON(5,7) 
300 MAT B=CON(5*Q,S) 
400 MAT A=CON 


Program Example: 


100 MAT A = CON(2,2) 
200 MAT PRINT A; 


When this program is executed, the CRI displays the 
packed format: 


1 1 
1 1 
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result in 


MAT= (MAT Assignment) Statement 


General Format: 


MAT a=b 


where: 
a and b are both numeric or both alphanumeric array names 


This statement replaces each element of array a with the 
corresponding element oof array 0b. Array a is implicitly 
redimensioned to conform to the dimensions of array b. 


Syntax Examples: 


100 DIM A(3,5),B(3,5) 
200 MAT A=B 

300 DIM C(4,6),D(2,4) 
400 MAT C=D 

500 DIM E(6),F(7) 

600 MAT F=E 


Program Example: 


1 1 1 9 8 7 
Let A= 1 1 1 B= 6 5 4 
1 1 1 


Program: 


100 DIM A(3,3),B(2,3) 
200 MAT A=CON 

300 MAT PRINT A 

400 MAT INPUT B 

500 MAT A=B 

600 MAT PRINT A 


When this program is executed, the constant three-—by-three array 
A is displayed as: 


1 1 1 
1 1 1 
1 1 1 


in zoned format; the array B is input through the keyboard, and the 
new array A is displayed as follows in zoned format. 


9 8 7 
6 5 4 
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MAT IDN (MAT Identity) Statement 


General Format: 


MAT c = IDN [(d1,d2)] 


where: 
c = numeric array name 
d1,d2 = expressions specifying new dimensions 
1<=d1,d2<=32767 


This statement causes the specified matrix to assume the form of 
the identity matrix. If the specified matrix is not a square matrix, 
an error occurs and execution is terminated. 


Using (d1,d2) causes the matrix to be redimensioned. If (dl1,d2) 


is not used, the matrix has the dimensions specified in a previous 
COM, DIM, or MAT statement. 


Syntax Examples: 


100 MAT A = IDN(4,4) 
200 MAT B = IDN 
300 MAT C = IDN(X,Y) 


Program Example: 


100 DIM A(4,4) 
200 MAT A = IDN 
300 MAT PRINT A 


When this program is executed, matrix A is displayed in zoned format 
as: 


oOoor 
oor oO 
Oro°o 
HH OOO 
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MAT INPUT Statement 


General Format: 


numeric array name [(d1[,d2])] j 
alpha array name [(d1L,d2])[lengthl] { °°" ’ 


MAT INPUT [literal,] { 


where: 
d = expression specifying a new dimension 
1<=d1,d2< =32767 


length = expression specifying maximum length of each alpha array element 
1<=length< =256 


The MAT INPUT statement allows the user to supply values from 
the keyboard for an array during the running of a program. The MAT 
INPUT statement displays the literal, if given, and a question mark 
(2), and waits for the user to supply values for the specified 
arrays. The dimensions of the array(s) are as last specified in the 
program (by a COM, DIM, or MAT statement), unless the user 
redimensions the array(s) by specifying the new dimension(s) after 
the array name(s). The maximum length for aiphanumeric§ array 
elements can be specified by including the length after the 
dimensions specification; if no length is specified, a default value 
of 16 is used. 


The values entered are assigned to an array row by row until the 
array is filled. If more than one value is entered on a line, the 
values must be separated by commas. Alphanumeric data with leading 
Spaces or commas can be entered by entering quotation marks before 
and after the data value. A value surrounded by single quotation 
marks (') is converted to lowercase; .values enclosed in double 
quotation marks (") remain in uppercase. Refer to Subsection 3.4.1 
for more information on the effect of quotation marks _ on 
alphanumeric values. 


Several lines can be used to enter the required data. Excess 
data are ignored. If there is a system-detected error in the 
entered data, the data must be reentered beginning with the 
erroneous value. The data that preceded the error are used as 
previously entered. Input data must be compatible with the array 
(i.e., numeric data for numeric arrays, alphanumeric literal strings 
for alphanumeric arrays). Entering no data on an input line (i.e., 
only keying ENTER to enter a carriage return) causes the remaining 
elements of the array currently being filled to be ignored. 
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Example with numeric variables: 


100 DIM A(2),B(3),C(3,4) 
200 MAT INPUT A,B(2),C(2,4) 


When this program is run, enter the values, separated by commas, 
~3, -5, .612, .41 


Press the ENTER key to enter these values for array elements A(1), 
A(2), B(1) and B(2). Enter the values 


-6.4, -5.6, 98 


separated by commas; press ENTER to enter these values for the array 
elements C(1,1), C(1,2), and C(1,3). Touch the ENTER key without 
entering further values to enter a carriage return and ignore the 
rest of the possible values for array C. 


Example with alphanumeric string variables: 


100 DIM C$(2),A$(4)4,B(3) 
200 MAT INPUT A$(4)3,B(2) ,C$ 


Enter RAD,DEG,MIN,SEC,2.5,5.6,LAST RESULT,"ROTATE X,Y", and press 
ENTER. 


Result: 
RAD 

A$ = DEG B= 2.5 C$ = LAST RESULT 
MIN 5.6 ROTATE X,Y 
SEC 
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MAT INV (MAT Inverse) Statement 


General Format: 


MAT c = INV(a)Ld] 


where: 
c and a = numeric array names 


d = numeric variable; the value of the determinant of the array a 


This statement causes the inverse of matrix a to be placed in 
matrix c. Matrix c is redimensioned to have the same dimensions as 
matrix a. Matrix a must be a square matrix; matrix c must be a 
floating-point matrix. If matrix a is singular (i.e., cannot be 
inverted) and d is specified, then d equals zero after MAT INV is 
encountered. If d is not specified, an error occurs. In either 
case, c is destroyed. A matrix can be replaced with the inverse of 
itself. 


After inversion, the variable d (if specified) equals the value 
of the determinant of matrix a. 


This statement uses the Gauss—Jordan Elimination Method done in 
place; as with any matrix inversion technique, results can be 
inaccurate if the determinant (or normalized determinant) of the 
matrix is close to zero. It is therefore good practice to check the 
determinant after any inversion. 


The Gauss-—Jordan Elimination Method also works best when values 
on the main diagonal are in the same range as other values in the 
matrix; in particular, numbers with large negative exponents on the 
main diagonal should be avoided when other values are not in this 
range. When in doubt, it is a good plan to check the data before 
inversion and adjust or rearrange it accordingly (for example, zero 
elements that are close to zero, or rearrange data so that elements 
on the main diagonal are as large as possible). 


Syntax Examples: 


100 MAT A=INV(B) 
200 MAT Z1=INV(P) ,X2 
300 MAT F=INV(C),J3 
400 MAT C=INV(C) 
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The following program takes the four-by-four matrix A from the 
calculates its inverse, 
and the value of the determinant of A. 


keyboard input, 


100 DIM A(4,4) 

PRINT "ENTER ELEMENTS OF A 4x4 MATRIX" 
MAT INPUT A 

MAT B=INV(A) ,D 

500 MAT PRINT B 


200 
300 
400 


and prints both the result 


=] 0 0 25 
-3.5 -2 -4 1 
0 1 0 0 

1 0 1 -.25 


600 REM B IS THE INVERSE OF A, D IS THE DETERMINANT OF A 
700 PRINT "VALUE OF DET.A=";D 
If array A= 0 2 4 8 then array B= 
0 0 1 0 
1 0 0 1 
4 8 16 32 
and the value of the determinant of A = -8. 
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MAT * (MAT Multiplication) Statement 


General Format: 


MAT c=a*b 


where: 
c, a, and b are numeric array names 


The product of arrays a and b is stored in array c. Array c 
cannot appear on both sides of the equation but a and b can be 
identical. If the number of columns in matrix a does not equal the 
number of rows in matrix b, an error occurs and execution is 
terminated. The resulting dimension of c is determined by the 
number of rows in a and the number of columns in b. 


syntax Example: 


100 DIM A(5,2),B(2,3),C(4,7) 
200 DIM E(3,4),F(4,7) ,G(3,7) 
300 MATG=E* F 
400 MAT C=A * B 


Program Example: 


100 DIM A(2,3),B(3,4) 
200 MAT INPUT A,B 
300 MATC=A*B 
400 MAT PRINT C 


Let A= 0 1 4 ,Be= 5 1 0 4 
7 7 7 4 1 0 4 
3 4 3 4 


When the program is executed and arrays A and B are entered, array C 
is displayed as: 


16 17 12 20 
84 42 21 84 
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MAT PRINT Statement 


General Format: 


MAT PRINT array name i} array cae ne if: 


The MAT PRINT statement prints arrays in the order given in the 
statement. Each matrix is printed row by row. All elements of a 
row are printed on as many lines as required. A multiple MAT PRINT 
is treated like several single MAT PRINTs. Numeric arrays are 
printed in zoned format unless the array name is followed by a 
semicolon, in which case the array is printed in packed format. 
For alphanumeric arrays, the zone length is set equal to the maximum 
length defined for each array element (not always 16). A vector (a 
one-dimensional array) is printed as a colum vector. 


Syntax Examples: 
100 DIM A(4),B(2,4),BS(10) ,C$(6) 


200 MAT PRINT A;B,C$ 
300 MAT PRINT A,B$ 


Program Example: 


This program takes nine alphanumeric quantities as input, each up to 
16 characters long, and prints them as a three-by-three array in 
packed format. 

100 DIM Z$(3,3) 

200 MAT INPUT Z$ 

300 MAT PRINT Z$; 
Enter the values: 

A, B, C, D, E, F, G, H, I 


Results: 


DEF 
GHI 
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MAT READ Statement 


General Format: 


numeric array name (d1[,d2]) aad 
eee oe array name \ Ke Ld2]) [length] \ | | 


where: 
d = expression specifying a new dimension 
1<=d1,d2< =32767 


length = expression specifying maximum length of each alpha array element 
1<=length< =256 


The MAT READ statement is used to assign values contained in 
DATA statements to array variables without referencing each member 
of the array individually. The MAT READ statement causes the 
referenced arrays to be filled sequentially with the values 
available from the DATA statement(s). Each array is filled row by 
row. Values are retrieved from a DATA statement in the order they 
occur on that program line. If a MAT READ statement references 
beyond the limit of existing values in a DATA statement, the next 
sequential DATA statement is used. If the program contains no more 
DATA statements, an error occurs and execution is terminated. 


Alphanumeric string arrays can also be used in the list. The 
information entered in the data statement must be compatible with 
the array (1.e., numeric values for numeric arrays, alphanumeric 
literals for alphanumeric arrays). 


The dimensions of the array(s) are as last specified in the 
program (by a COM, DIM, or MAT statement), unless the user 
redimensions the array(s) by specifying new dimension(s) after the 
array name(s) in the MAT READ statement. The maximum length for 
alphanumeric array elements can be specified by including the length 
after the dimension specification; when no length is specified, a 
default of 16 is used. 


Program Example: 
100 DIM A(1),B(3,3) 
200 MAT READ A,B(2,3) 
300 DATA Ly = 2; 310% -.398, 6.21, 0, 0 
400 MAT PRINT A,B 
Result: 


A= 1 B = -.2 315 ~.398 
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MAT REDIM Statement 


General Format: 


MAT REDIM redim-elt[,redim-elt] . . . 


where: 
veairaleree Joncas array name (exp1 [,exp2]) \ 


alpha array name (exp1[,exp2])[exp3] 


1<=exp1 < 32767 
1 <=exp2 < 32767 
1<=exp3 < 256 


The MAT REDIM statement redimensions the specified arrays to the 
dimensions specified by the expressions. The rules for MAT REDIM 
statements are the same as those for DIM statements, except as 


follows: 


1. 


2. 


a. 


As indicated, alpha scalars cannot be redimensioned. 


MAT REDIM can occur anywhere in the program or subprogram. 
Its only effect is to change the dimensions and lengths of 
the specified array; it does not affect the values currently 
assigned to array elements. 


The total (byte) space required for the array must be no 
greater than that initially allotted to it by DIM or default 
(10 by 10, length = 16 for alpha arrays). 


If exp3 is omitted, it is set to 16, regardless of the 
previous length. 


A matrix cannot be redimensioned as a vector, or vice versa. 


Syntax Examples: 


100 MAT REDIM A(10),B$(10,20)10 
200 MAT REDIM A(20,30) 
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MAT()* (MAT Scalar Multiplication) Statement 


General Format: 


MAT c = (k) ¥a 


where: 
c and a are numeric array names and k is an expression 


Each element of the array a is multiplied by the value of 
expression k; the product is stored in array c. Array c can appear 
on both sides of the equation. Array c is redimensioned to the same 
dimensions as array a. 


Syntax Examples: 


100 MAT C = (SIN(X))*A 
200 MAT D = (X+Y¥*2)*A 
300 MAT A = (5)*A 


Program Example: 


This program allows the user to enter a three-by-three array and 
a scalar. It then performs scalar multiplication and displays the 
result. 


100 PRINT "ENTER DATA FOR A 3x3 ARRAY" 
200 MAT INPUT C(3,3) 

300 PRINT “ENTER SCALAR" 

400 INPUT K 

500 MAT A = (K)*C 

600 MAT PRINT A; 


Let C = 5 3 1 ,/>K= 5 then A = 25 15 5 
2 2 2 10 10 10 
1 1 1 5 5 5 
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MAT — (MAT Subtraction) Statement 


General Format: 


MAT c=a-b 


where: 
a, b, and c are numeric array names 


This statement subtracts numeric arrays of the same dimension. 
The difference of each pair of elements is stored in the 
corresponding element of c. Any two or all of a, b, and c can be 
the same. An error occurs and execution is terminated if the 
dimensions of a and b are not the same. Array c is redimensioned to 
have the same dimensions as arrays a and b. 


Syntax Example: 
100 DIM A(6,3),B(6,3),C(6,3),D(4) ,E(4) 


200 MAT C =A - B 
300 MATC=A-C 
400 MATD=D-E 


Program Example: 


100 DIM D(3,3), E(3,3) 
200 MAT INPUT D 

300 MAT INPUT E 

400 MATF=D-E 

500 MAT PRINT F 


If D= l 11 ##+, E=3 3 3, then F= - -2 -2 
111 3 3 3 —2 —-2 -2 
2 2 2 3 3 3 -1 -1 -l 
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MAT TRN (Transpose) Statement 


General Format: 


MAT c = TRN(a) 


where: 
a and c are array names (both numeric or both alphanumeric) 


This statement causes array c to be replaced by the transpose of 
array a. Array c is redimensioned to the same dimensions as the 
transpose of array a. Array c cannot appear on both sides of the 
equation. 


Syntax Example: 


100 MAT C = TRN(A) 


Program Example: 


100 DIM A(3,3) 
200 MAT INPUT A 
300 MAT C = TRN(A) 
400 MAT PRINT C 


Let A = 9 8 7 
6 5 4 
3 2 1 


When the program is executed, C is displayed as: 


foe) 
Polo 
Nw 
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MAT ZER (MAT Zero) Statement 


General Format: 


MAT c = ZER [(d1Ld2])] 


where: 
c = numeric array name 
d1,d2 = expressions specifying new dimensions 
1 <=d1,d2 <= 32767 


This statement sets all elements of the specified array equal to 
zero. Using (dl,d2) causes the matrix to be redimensioned. If 
(dl,d2) is not used, the matrix retains the dimensions specified in 
a previous COM, DIM, or MAT statement. 


Syntax Examples: 


100 MAT C = ZER(5,2) 
200 MAT B = ZER 

300 MAT A = ZER(F,T+2) 
400 MAT D = ZER(20) 
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Mathematical Functions 


The following General Form 1 applies to most mathematical 
functions. General Forms 2 through 4 are listed after the discussion 
of General Form 1. 


General Format 1: 
function (exp) 
where: 


SIN 

COS 
TAN 
ARCSIN 
ARCCOS 
ARCTAN 


ee ATN 
function = ABS 


EXP 
INT 
LGT 
LOG © 
SGN 
SOR 


Trigonometric Functions 


The sine, cosine, tangent, arcsine, arccosine, and arctangent 
functions are available in BASIC. Other trigonometric functions can 
be specified easily using these functions in expressions. (When 
using these functions in combination, care must be taken to avoid 
Significant data conversion errors. See Appendix C for a complete 
discussion. ) 


Function Name Sample Expression Meaning 


SIN SIN (X) The sine of the argument 

COS COS (X) The cosine of the argument 

TAN TAN (X) The tangent of the argument 

ARCSIN ARCSIN(X) The inverse sine of the argument 
ARCCOS ARCCOS (X) The inverse cosine of the argument 
ARCTAN ARCTAN (X) The inverse tangent of the argument 
ATN ATN(X) Synonym for ARCTAN. 
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Other Numerical Functions 


The remaining numerical functions are described below. 


Function Name 


ABS ABS (X) 
SOR SOR(X) 
EXP EXP (X) 
INT INT (X) 
LGT LGT(X) 
LOG LOG(X) 
SGN SGN (X) 


Sample Expression 
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Meaning 


The absolute value of the 
argument: -X if X < 0; X 
if X¥>=0. 


The square root of the 
argument; X raised to the 
.5 power. 


The exponential function; 
"e" (2.718...) raised to 
the X-th power. 


The greatest-integer 
function; the greatest 
integer less than or 
equal to the argument. 


Common (base 10) 
logarithm. 


Natural (base "e") 
logarithm; inverse 
function of EXP. 


The signum function; -1 
if the argument is 
negative; O if the 
argument is zero; +1 

if the argument is 
positive. 


Mathematical Functions (Continued) 


General Format 2: 


function (exp[,exp] . . .) 


where: 
Bos 23 MAX 
function = ae \ 


Function Name Sample Expression Meaning 

MAX MAX(X,Y,Z) The value of the largest 
element in the argument 
list. 

MIN MIN(X,Y,Z) The value of the smallest 
element in the argument 
list. 
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Mathematical Functions (Continued) 


General Format 3: 


MOD (exp,exp) 


Function Name Sample Expression Meaning 
MOD MOD (X,Y) The modulus function; 


the remainder of the 
division of the first 
element by the second. 
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Mathematical Functions (Continued) 


General Format 4: 


Pl 


Function Name Sample Expression Meaning 
PI PI The value 
3.14159265358979323. 


See Section 2.6 for more information on Numeric Functions. 
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MAX Function 


General Format: 


MAX(explLexp] . . .) 


where: 
exp = a numeric scalar or numeric array 


The MAX function returns the largest element in the argument 
list, or, in the case of an array, the largest element in the array. 


Syntax Examples: 


100 A=MAX(B,C,D) 
200 D=MAX(E()) 


Numeric Examples: 


MAX(4,3,2,1) = 4 
MAX(10,100,1000) = 1000 
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MIN Function 


General Format: 


MIN(expL.exp] . . .) 


where: 
exp = anumeric scalar or numeric array 


The MIN function returns the smallest element in the argument 
list or array. 


Syntax Examples: 


100 MIN (B,C,D) 
200 MIN (E()) 


Numeric Examples: 


MIN(4,3,2,1) = 1 
MIN(10,100,1000) = 10 
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MOD Function 


General Format: 


MOD (numeric exp, numeric exp) 


The MOD (modulus) function returns a numeric value equal to the 
remainder of the division of the first expression by the second. 
The value returned is an integer value if both expressions are 
integers; otherwise it is floating-point. 


Syntax Example: 


100 Y = MOD(7,4) 


Numeric Example: 
MOD(5,3) = 2 
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NEXT Statement 


General Format: 


NEXT numeric scalar variable [,numeric scalar variable] . . . 


The NEXT statement defines the end of a FOR...NEXT loop. It 
must contain the same index variable(s) as a previously executed FOR 
statement. A multiple NEXT is executed left to right. For example, 
NEXT I,J,K 


is equivalent to 


NEXT I 
NEXT J 
NEXT K 

When a FOR...NEXT loop is encountered, the index variable takes 
the value initially assigned in the FOR statement. When the NEXT 
statement is executed, the STEP value specified in the FOR statement 
is added to the value of the index. (If no STEP value is given, +1 
is used.) If the result is within the range specified in the FOR 
statement, the result (index + STEP) is assigned to the index 
variable and execution continues at the statement following the FOR 
statement. If the result is outside the range specified in the FOR 
statement, the index variable is unaltered and execution passes to 
the statement following the NEXT statement. The FOR...NEXT loop is 
then considered complete. A NEXT without a preceding FOR with the 
same index variable produces a run-time error. 


Syntax Example: 
100 NEXT I 


II-104 


NUM Function 


General Format: 


NUM (alpha-exp) 


The NUM function determines the number of sequential ASCII 
characters in the specified alpha-expression that represents a legal 
BASIC number. Numeric characters are defined as digits 0 through 9 
and special characters E, . (decimal point), +, -, and space 
(provided the space is not embedded; leading and trailing spaces are 
considered numeric characters, embedded spaces are not). The 
percent sign (%) is not a legal numeric’ character. Numeric 
characters are counted starting with the first character of the 
alpha-expression. The count ends when a non-numeric. character 
occurs, or when the sequence of numeric characters fails to conform 
to standard BASIC number format. Leading and trailing spaces are 
included in the count. 


Thus, NUM can be used to verify that an alphanumeric value is a 
legitimate BASIC representation of a numeric value, or to determine 
the length of a numeric portion of an alphanumeric value. NUM can 
be used wherever numeric functions are normally used. NUM is 
particularly useful when it is desirable to numerically validate 
input data under program control. If A$="1E88", NUM(A$)=16 even 
though 1E88 is an illegal value, since 1E88 exceeds the legal size 
for a floating point constant. This occurs because NUM checks only 
format, not value. 


The result of the NUM function is an integer. 


Examples: 


100 AS = "98.74+53.6" /* X=4 since the sequence of numeric */ 

200 X=NUM(A$) /* characters fails to conform to standard */ 
/* BASIC number format when the + character */ 
/* is encountered. */ 


100 INPUT A$ /* The program illustrates */ 
200 IF NUM(A$)=16 THEN 500 /* how numeric information */ 
300 PRINT"NON-NUMERIC,ENTER AGAIN" /* can be entered as a */ 

400 GOTO 100 /* character string, */ 

500 CONVERT A$ TO X /* numerically validated, */ 
600 PRINT "X=";X /* and then converted to an */ 
Run program: /* internal number. */ 

2? 123A5 

NON-NUMERIC, ENTER AGAIN 

? 12345 

X=12345 
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ON Statement 


General Format: 


ON expression ees, entry [entry]... 


where: 


line number 
entry = < null 
statement label 


The /ast entry must be a line number or a statement label (no trailing commas). 


The ON statement is a computed GOTO or GOSUB statement. 


If I is the truncated value of the expression, transfer is 
determined by the Ith entry: 


1. If a line number or statement label, the transfer is made to 
that line: or statement. 


2. If null, no transfer is made. 


3. If I is less than. 1 or greater than the number of entries, 
no transfer is made. 


In options 2 or 3 above, execution continues at the next 
executable statement. For example, ON X GOTO,,100,200,,300,,,400 


Value of X Transfer 


KF OW ON HU PWNeF OF N 


none 
none 
none 
none 
none 
100 

200 

none 
300 

none 
none 
400 

none 
none 


eb 


Syntax Example: 


100 ON I GO TO 500, 600, 700 
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OPEN Statement 


General Format: 


NOGETPARM EXTEND 


OPEN [] eee \ u| file-exp) < SHARED 
OUTPUT 


|, SPACE = num-exp1] [,DPACK =num-exp2] [IPACK = num-exp3] 
LFILE = alpha-exp1] [LIBRARY = alpha-exp2] 

[, VOLUME = alpha-exp3] [,FILESEQ = num-exp4] 

[, BLOCKS = num-exp5] 


‘where: 


alpha-exp1,2,3 = file, library, and volume names must be enclosed in quotation marks 


Filename.=:at most 8 characters (remainder ignored) 


Library = at most 8 characters (remainder ignored) 


Volume = at most 6 characters (remainder ignored) 


num-exp5 = size of I/O buffer (in blocks of 2048 bytes) 
default = 1 block 


(use of other parameters explained below) 


OPEN is used to open an existing disk or tape file or to create 
anew file. The OPEN statement is discussed in detail in Subsection 
8.3.2. The file number (provided by file-exp) must have appeared in 
a SELECT statement (see SELECT). BLOCKS is optional, but file, 
library, and ‘volume names are requested by the system (using the 
SELECT prname) even if included in OPEN, unless the file was opened 
and closed previously or NOGETPARM or NODISPLAY was specified. 


The various QPEN modes for old and new files, -and the allowed 
I/O operations, are listed in Table II-5. 


Attempting to OPEN a file that is already open and has not yet 
been closed causes an irrecoverable error at run time. 
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Use of the SPACE, DPACK, IPACK, NODISPLAY, and NOGETPARM fields 
is explained below. 


NODISPLAY, NOGETPARM 


When opening a file in the program, OPEN normally issues a 
GETPARM (see the discussion of GETPARM in the VS Procedure Lanquage 
Reference) to the workstation or procedure, requesting the FILE, 
LIBRARY, and VOLUME parameters. The prompt at the workstation can 
be suppressed by specifying NODISPLAY. This should only be done if 
the correct FILE, LIBRARY, and VOLUME are specified in this or a 
previous OPEN, or in a procedure, or if SET defaults are in use. 
(For a discussion of SET usage constants, see the VS Programmer's 
Introduction.) Both the workstation prompt and the procedure file 
prompt can be suppressed by specifying NOGETPARM. This should not 
be done if the file parameters are to be accessible or modifiable 
from a user procedure. (For a discussion of procedures, see the VS 


Procedure Language Reference. ) 


The remaining parameters differ in usage depending on whether 
the file is being opened in OUTPUT or non—-OUTPUT mode. 


SPACE 
OUTPUT: Specifies the approximate number of records to be 
put in the new file. If OUTPUT is not specified, a 
GETPARM is displayed. 


non-—OUTPUT: If a variable (i.e., a receiver), it contains the 
number of records currently in the file after OPEN. 


DPACK, IPACK 
OUTPUT: Specifies the block packing densities (integer) for 
the records (DPACK) or keys (IPACK), respectively, 
for a new indexed file only. 
non-OUTPUT: Ignored 
In any mode, if FILE/LIBRARY/VOLUME are alpha-receivers, the 


actual names are returned to the receivers after the OPEN statement 
is completed. 


FILESEQ 
File Sequence number (for tape files only). 
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Table II-5. Legal Function Requests and Descriptions 


INDEXED 
MODE CONSEC | VAR CONSEC VAR INDEXED TAPE 


PRINTER 


10 
(old files 
only) 


SHARED 
(old INDEXED 
files; 
old or new 
CONSEC files 


OUTPUT 


(new files 
only) 
(old files 
deleted) 


EXTEND 


(old files 
only) 


Ops: READ, SKIP 


Consecutive or 
relative READ 
or SKIP, 
Starting from 
beginning of 
file. 


Ops: READ, REWRITE, 
SKIP 


Consecutive or 
relative READ 

or SKIP starting 
from beginning of 
file, with HOLD/ 
REWRITE option. 


NOT ALLOWED 


Ops: WRITE 


Writes records 
consecutively 
to a new file. 


Ops: WRITE 


Writes records 
consecutively, 
starting at the 
current file end. 


Ops: READ,SKIP 


Consecutive or 
relative READ or 
SKIP starting 
from beginning 
of file. 


Ops: READ,SKIP, 
REWRITE 


Consecutive or 
relative READ 
or SKIP starting 
from beginning 
of file, with 
HOLD/REWRITE 
option. 


Ops: WRITE, 
HOLD, RELEASE 


Used for (vari- 
able length) 
log files. 


Ops: WRITE 


Writes records 
consecutively 
to a new file. 


Ops: WRITE 


Writes records 
consecutively, 
starting at the 
current file end. 


Ops: READ 


Consecutive or 
keyed READ, 
Starting from 
beginning or 
after last 
record read. 


Ops: READ,WRITE, 
REWRITE, DELETE 


Consecutive or 
keyed READ or 
WRITE starting 
from beginning 
of (key) file, 
with HOLD/REWRITE 
DELETE option. 


Ops: READ,WRITE, 
REWRITE, DELETE 
HOLD, RELEASE 


Same as I0, but 
allows multiple 
access, indepen- 
dently, HOLD 
protection. 


Ops: WRITE 


Writes records 
to a new file - 
(primary) keys 
must be in as- 
cending order. 


NOT ALLOWED 
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Ops: READ,SKIP NOT ALLOWED 


Consecutive or 
relative READ or 
SKIP starting 
from beginning 
of file. 


Ops: READ,SKIP NOT ALLOWED 


Consecutive or 
relative READ or 
SKIP starting 
from beginning 
of file, with 
HOLD option. 


NOT ALLOWED NOT ALLOWED 


Ops: WRITE Ops: WRITE 


Writes records 
consecutively 
to a new file. 


NOT ALLOWED 


Writes records 
consecutively 
to a new file. 


NOT ALLOWED 


Syntax Examples: 


100 OPEN NODISPLAY #1,10,FILE=""THOMAS", LIBRARY="STEARNS", ! 
200 VOLUME="ELIOT" 

300 OPEN #2 ,OUTPUT 

400 OPEN NODISPLAY #3, INPUT, VOLUME="TAPE1", FILESEQ=1 
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OR Logical Operator 


General Format: 


[LET] alpha-receiver = [logical exp] OR logical exp 


logical exp: see Section 5.7 


The OR operator performs a logical OR operation on two or more 
alphanumeric arguments. 


Example: 
100 A$= "SAINT" 
200 BS= "S " 
300 C$= A$ OR BS 
400 PRINT C$ 


Output: Saint 


Capital A is HEX(41) (01000001 in binary) and a blank space is 
HEX(20) (00100000 in binary). When two characters are ORed, a 
binary one in either becomes a binary one in the result. Thus, 
ORing A with " " produces binary 01100001 or HEX(61), which is the 
ASCII "a". 


The operation proceeds from left to right. If the operand 
(logical expression) is shorter than the receiver, the remaining 
characters of the receiver are unchanged. If the operand is longer 
than the receiver, the operation stops when the receiver is 
exhausted. 


See Section 5.7 for more information on logical expressions. 


II-111 


PACK 


General Format: 


PACK PIC (image) alpha-receiver FROM 
— rl ereaaled | | { numeric array-designator \ " | 


expression expression 


where: 
image = [+] [#.. JL M#...1(T{ TT] (atleast 1 #) 


The PACK statement packs numeric values into an alphanumeric 
receiver, reducing the storage requirements for large amounts of 
numeric data where only a few significant digits are required. The 
specified numeric values are formatted into packed decimal form (two 
digits per byte) according to the format specified by the image, and 
are stored sequentially into the specified alphanumeric receiver. 
Receivers are filled from the first byte until all numeric data are 
stored. An entire numeric array can be packed by specifying the 
array with a numeric array-designator (e.g., N()). An error results 
if the receiver is not large enough to store all the numeric values 
to be packed. 


The image is composed of # characters to signify digits, and, 
optionally, +, -, ., and fT characters to specify sign, decimal point 
position, and exponential format. The image can be classified into 
two general formats: 


Format Example 
Fixed Point +H . +4 
Exponential + . HH 


Numeric values are packed according to the following rules: 


1. Two digits are packed per byte. A digit is stored for each 
# in the image. 


2. If a sign (+ or -) is specified, it occupies the high-order 
half-byte. A single hexadecimal digit is used to represent 
both the sign of the number and the sign of the exponent for 
exponential images. The four bits of this hexadecimal digit 
are set as follows: 


Bit 1 (leftmost) set to 1 if exponent is negative. 
Bit 2 OFF ("0"). 
Bit 3 OFF ("0"). 
Bit 4 (rightmost) set to 1 if number is negative. 
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If no sign is specified, the absolute value of the number is 
stored, and the sign of the exponent is assumed to be 
positive (+). 


The decimal point is not stored. When unpacking the data 
(see UNPACK), the decimal point position is specified in the 
image. 


The packed numeric value is_7 left-justified in the 
alpha-receiver, with the sign digit (if specified) occupying 
the high-order half-—byte, followed by the number in packed 
decimal format (two digits per byte). The exponent occupies 
the two low-order half-bytes (if specified). The packed 
value always requires a whole number of bytes, even if the 
image calls for other than a whole number. For example, the 
image "###" calls for 1-1/2 bytes, but 2 bytes are 
required. In such cases, the value of the unused half-—byte 
(the low-order half-byte) is not altered by the PACK 
operation. 


If the image has format 1, the value is edited as a fixed- 
point number, truncating or extending any fraction with 
zeros and inserting leading zeros for nonsignificant integer 
digits according to the image specification. An error 
results if the number of integer digits exceeds the format 
specification. 


If the image has format 2, the value is edited as an 
exponential number. The value is scaled as specified by the 
image (there are no leading zeros). The exponent occupies 
one byte, and is stored as the two low-order hex digits in 
the packed value. 


Example of Storage Requirements: 


HHH = 2 bytes 
HHH = 2 bytes 
+44 . HHH = 3 bytes 
+H . $4 = 2 bytes 


Syntax Examples: 


100 


PACK PIC (#####)A$ FROM X 


200 PACK PIC (#HHE)STR(A$,4,2) FROM N(1) 
300 PACK PIC (##.##)A1$() FROM X,Y,N(),M() 


II-113 


$SPACK/$UNPACK Statements 


General Formats: 


$PACK [ [4e2}] aphex |abpnrecie FROM arglLarg)... 


GOTO line number 
| ‘DATA eae — wa 
where: 


line number = line number or statement label of 
statement label data conversion error exit 


exp 
arg = < alpha-exp, EXCEPT alpha array string 
array-designator 


$UNPACK [ fo=} sone-o)| alpha-exp TO argLarg]... 


GOTO line number 
| ‘DATA ee ao soa 


where: 
ata‘ receiver, EXCEPT alpha array string 
g array-designator 


$PACK and $UNPACK pack and unpack numeric and character data, in 
any of several formats specified by the user, into’ the 
alpha-receiver or from the alpha-expression, respectively. 


The following considerations apply to $PACK and $UNPACK 
operation: 


1. An argument of the form "name$()" is always recognized as an 
array of elements, never as an alpha array string. Use the 
STR function to produce an array string. 


2. Array elements are generally considered as _ individual 
consecutive values or receivers (row by row). The exception 
is F format, in which a single format applies to all of the 
array elements. 


3. $PACK generates an error (or exit) if the alpha-receiver is 
not long enough to store all of the arguments in _ the 
specified format. This is true with any of the formats. 


4. $UNPACK generates an error (or exit) if the unpacked data 
are not the same type (alpha, numeric) as the receiver. 
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Delimiter Format 


Indicated by the presence of "D = alpha-expression". The format 
of the data packed by $PACK is: 


where DEL is the user-specified delimiter. 


The alpha-expression following "D=" must contain at least 2 
bytes: 


byte 1 = Conversion code. This is used only by $UNPACK, but 
must have one of the four legal values for either $PACK 
or $UNPACK: 


Hex Value ($UNPACK) Result 
00 A) Error if insufficient data in the 
buffer. 


B) Skip a receiver (or array element) for 
each extra delimiter encountered. 

01 A) No error if insufficient data in the 
buffer --— remaining receivers are left 
unchanged. 

B) Skip a receiver for each extra 
delimiter. 

02 A) Error if insufficient buffer data. 

B) Ignore extra delimiters. 
03 A) No error if insufficient buffer data. 
B) Ignore extra delimiters. 


byte 2 = (DEL) delimiter character. 
1. PACK: 


The general form is as diagrammed above. The structure of 
the data entries is as follows: 


a. Numeric -- Exactly like PRINT, without the trailing 
blank. 


b. Alphanumeric —— Defined length is stored. 
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2. $UNPACK: 


Extra delimiters can be present, as described in the 
conversion code above. A missing final delimiter causes the 
last data value to be considered as extending to _ the 
(defined) end of the buffer (alpha-expression). The 
specific data entries allowed are: 


a. Numeric -- can be any numeric constant that is allowed 
on a program line, including leading and trailing 
blanks. Exception: as with CONVERT, "%" is not 
recognized as a legal character. 


b. Alphanumeric -- can be anything, any length. 
Alphanumeric entries are right-padded or truncated to 
fit the receiver. 


NOTES 


$UNPACK condition code can be set not to cause an error 
if there are too few data values in the buffer; this is 
true only of delimiter (D) format. In any of the other 
formats, an error (or DATA exit) results if the buffer 
has insufficient data. 


Any errors in executing $PACK and $UNPACK do not affect 
values already packed or unpacked in the same 
statement. As is the case with regular PACK and UNPACK 
statements, the error occurs only when the _ first 
erroneous conversion is encountered. 


Field Format 


Indicated by the presence of "F = alpha-expression". The format 
of the data packed by $PACK is: 


fsima | ine [sna |. | ine | sine 


where field = a skip field 
a formatted data value 


The alpha-expression following "F=" must contain at least as 
many pairs of bytes as there are arguments in the argument list. 
(Each pair corresponds to an argument, whether it is a scalar or 


array argument.) 
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From left to right, each argument has a corresponding byte pair, 
in which: 


L. 


2. 


byte 2 = field width (bytes) in hex >0 
byte 1 = field type 


Byte 1 Value Resulting Field Type 


00 skip field 
10 free—format 
2hp ASCII integer format 
3hp IBM display format 
4hp WANG display format 
5hp IBM packed decimal format 
AO alphanumeric field 
(hp = the number (in hexadecimal) of places to the right 
of the implied decimal point.) 
Field Types 
1. QO --— Skip 


In either $PACK or $UNPACK, skips the specified number of 
bytes in the buffer; skipped characters are unchanged. 


AQ -— Alphanumeric 

For alphanumeric data; in either $PACK or $UNPACK, the value 
is padded or truncated on the right to fit the field or 
receiver, respectively. 


10 -- Free-Format ASCII Numeric 


$PACK: Same as delimiter format (i.e., same as PRINT) but 
right—padded or truncated to fit the field. 


$UNPACK: Same as delimiter $UNPACK fields. 


2hy —- ASCII Implied Decimal 


Form: 


(ASCII) digit 0 through 9 
sign byte 


where d 
s 


$PACK: format as shown; sign byte is ASCII 
(+ = HEX(2B), - = HEX(2D)). 


$UNPACK: format as shown; all the zone half-bytes are 
ignored and thus can have any value. 


II-117 


3h, -- IBM Numeric Display Format 


Form: 


h = hexadecimal digit from 0 to 9 only 
hs = sign digit 


$PACK: format as shown 


hs = Cc (+) 
D (-) 


$UNPACK: format as shown; Fs are ignored. 


4h, -- WANG VS Display Format 


Form: 


h = hexadecimal digit from 0 to 9 only 
hs = sign digit 


$PACK: format as shown 


$UNPACK: format as shown; 3s ignored 


hs = D (-) 
all else (+) 
Shy —- IBM Packed Decimal Format 
Form: 


h = hexadecimal digit from 0 to 9 only> 
hs, = sign digit 


$PACK: format as shown; hs = C (+) 
D ( 
$UNPACK: format as shown; h, = A,C,E,F (+) 
B,D (-) 
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Field types 4 through 7 have the following characteristics in common: 


In $PACK, an overflow causes an error, but the field is 
filled with zeros and the correct sign. 


In 2hp , 3hp ., and 4h, zoned format, zones are not 
checked when $UNPACKed, and thus can take on any values. 
This includes the zone of the sign byte in 2h format. One 
consequence of this is that blanks are interpreted as zoned 
zeroes in 2hp, 3p, 4hp. 


h in the format specification denotes the number of P digits 
to the right of the implied decimal point. It can take on 
any hexadecimal digit value, and can be larger than the 
number of digits in the field (in which case leading decimal 
zeroes are implied). 


In $PACK, an underflow causes no error and fills the field 
with zeros and a + sign, regardless of the sign of the 
expression itself. 


$PACK inserts leading and trailing zeros where necessary. 
$UNPACK allows any number of digits. ‘Only the first 15 


Significant digits are used; the rest only serve to position 
the decimal point. 


2200 Disk Storage Format 


Indicated by the absence of both D and F. 


Form: 


CONTROL 


where: 


CONTROL 


Pseudo-2200 control bytes (2) 


data = numeric or alpha value 
EOB = end-of-block byte 
= HEX(FD) 
SOV = 2200 Start-of-value byte for the next data value 
Th in a AS EE es ee 
8S <---------------- Loa nen ne > 
where: 
S = 0O = numeric L = length in bytes (binary) 
1 = alpha 
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$PACK Data Format 
1. Numeric 


Form: 


Value is decimal floating point. 


hs = sign indicator 
= 0, number +, exponent 
1, number —, exponent 
8, number +, exponent 
9, number -, exponent 


+ + 


hu he = exponent (units before tens) 
hi to hi3 = mantissa, in the usual order, with the 


decimal point assumed between h; and 
h2. 


2. Alphanumeric 


2 ee ee ae ee ee 


The defined length is stored. 


Form: 


3. Control bytes —- HEX(8001) 
$UNPACK Data Format 


1. Numeric -—- Same as $PACK, but allows any sign digit: 


$PACK SUNPACK 
0 0,2,4,6 
1 1,3,5,7 
8 8,A,C,E 
9 9,B,D,F 


This occurs because the 2 middle bits of the hexadecimal 
digit are ignored. 


2. Alphanumeric -- Any length, padded or truncated on the right 
to fit the receiver. 


3. Control bytes -- Ignored. 
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Syntax Examples: 


100 $PACK (D=D$)B3$() FROM T1,T1$(),1T3$,T2,DATA GO TO 210 
200 $UNPACK (D=D4$(1)) STR(B3$(),,15) TO T$(),DATA GO TO 210 
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PI Intrinsic Constant 


General Format: 


PI 


The intrinsic constant PI can appear anywhere a numeric 
expression can appear. It has the value 3.14159265358979323. 


syntax Example: 
100 AREA = PI * RADIUST2 
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POS Function 


General Format: 


POS ([-]_ alpha-exp ae alpha-exp) 


The POS function searches the first alpha-expression for a 
character that bears the appropriate relationship (<, <=, >, >=, <>, 
or =) to the first character of the second alpha-expression and 
returns the location (leftmost=1) of the first such character 
found. The basis of comparison is the ASCII codes of the 
characters. POS searches the entire defined length of the 
alpha-—expression. 


If no "-" is present, the search executes from left to right, 
and returns the position of the leftmost such character. If "-" is 
present, the search executes from right to left, and returns the 
position of the rightmost character. 


If no character satisfies the condition, POS=0. The output of 
POS is an integer. 


Syntax Examples: 


100 A%=POS (-A$<STR(B$,2,2)) 
200 FOR A=1 TO 10 STEP POS(C$=BS$) 
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PRINT Statement 


General Format: 


USING line no. [, expression] -\ fexpression]] ... ' 
stmt label , ' 
[prt-elt] K :S [prt-elt] | mr If: | 
where: 


ee character prt-elt 
prt-eit = ene prt-elt \ 


PRINT 


num-exp 
character prt-elt = < alpha-exp 
HEXOF (alpha-exp) 


BELL 

PAGE 

SKIP[(num-exp)] 

TAB (num-exp) 

COL(num-exp) 

AT (num-exp, num-exp [,[ num-exp]]) 


control prt-elt = 


The PRINI statement routes output to either the workstation or 
printer, depending on which device is currently selected (see the 
SELECT statement). 


The placement and format of the data that are output are 
controlled either by the use of auxiliary format control (FMT and 
Image (%)) statements, or by the use of the control print elements 
described below. If a format control statement is used, the PRINT 
statement must contain a USING clause referring to the FMT or 
Image (%) by line number or statement label. 


In either case, output begins at the current print position, as 
determined by the last output operation to the selected device 
(current print position is indicated on the workstation by the 
position of the cursor). After the PRINT statement is executed, the 
new current print position depends on how the PRINT statement ends. 
If the PRINT statement ends in a semicolon, a comma, or a control 
print-element, the current print position is the first position 
after the last character output; otherwise, the current print 
position is the first position of the next line. 


For PRINT output, the output line is divided into as many zones 
of 18 characters as possible; thus, a 132-column printer has seven 
zones, and the workstation has four. The last zone can be longer 
than the rest, extending to the end of the line. 
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Expressions and other print-elements in a PRINT statement must 
be separated by commas or semicolons. If USING is specified, these 
are equivalent and serve only to delimit one expression from the 
next. If USING is omitted, however, a comma after a character 
print-element causes the next print-element to begin at the start of 
the next zone (if the current print position is already in the last 
zone of a line, the next print-element starts at the beginning of 
the next line). A semicolon causes no change in print position. 
After a control print-element, commas and semicolons are equivalent. 


A line is not sent to the printer until either the print 
position is moved beyond the line or a SKIP(0) is encountered. See 
Chapter 7 for more information on output to the workstation and 
printer. 


The following discussion of print-elements does not apply to 
PRINT statements that specify USING. For details on the operation 
of the USING clause, see the entries for the FMT and Image (%) 
statements. 


Print Elements 


1. Numeric Expression 


a. If J|exp|<10°' or  fexp|>=10'*°, the format is 
exponential: 
SMDMMMMMMMMMME + XXb 
where: minus sign if negative, blank otherwise. 
mantissa digit. 
decimal point. 
XX = exponent digits. 
b = blank. 


S) 
M 
D 


For example, PRINT .000074679; 


Result: b7.4679000000E—05b 
start end 


b. If 10°' <= |exp] < 10'°, the format is fixed-point: 
S(Z...]({DF...Jb 


minus sign if negative, blank otherwise. 
zoned digit. 

decimal point. 

fixed digit. 

trailing blank. 


where: 


S 
Z 
D 
F 
b 


Hou ou ub ou 


and total Zs + total Fs <= 15. 
Leading zeros and trailing (decimal) zeros are not 
- printed (but zero is printed as 'b0b'). Up to 15 digits 
plus a decimal point, if any, are printed. 
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Alpha-expression 


The actual length of the alpha-expression is printed. 
Trailing blanks of an alpha variable or array string are not 
printed. 


HEXOF (alpha-expression) 


The hex value (defined length) of the alpha-expression is 


printed. (This includes trailing blanks --— HEX(20).) For 
example, 
100 DIM A$ 5 


200 A$ = "ABC" 
300 PRINT "HEX VALUE OF A$ =";HEXOF (A$) 


Result: HEX VALUE OF A$ = 4142432020 

PAGE 

Printer: Advances to line 1, column 1 of a new page. 
Workstation: Clears the screen and moves the cursor home. 
BELL 

Printer: Ignored. 


Workstation: Sounds the workstation alarm; the screen and 
cursor are unaffected. 


SKIP [(n)] 


Printer: Advances the print position to column 1 of the nth 
line after the current line (default n=1). 


If n=0, the current line is printed with a carriage return 
but no linefeed. This causes the next line to overprint. 


If n<O, SKIP is ignored. 


Workstation: Advances the cursor print position to column 1 
of the nth line after the current line (default=1). 


If n>0, the cursor moves down n lines. In cases in which 
the cursor must move to a line off the screen (i.e., current 
line + n >24), a roll-up occurs instead. The cursor is 
positioned at the beginning of the last line moved to (the 
bottom line of the screen if one or more roll-—-ups occurred). 


If n=0, the cursor returns to the beginning of the current 
line. 


If n<O, the cursor moves up n lines. A move to a line off 
(above) the screen causes a_ roll-down. The cursor is 
positioned at the beginning of the last line moved to (the 
top line of the screen if 1 or more roll-—downs occurred). 
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7. TAB(n) 


Printer: (n>0). The print position advances to column n of 
the current line. If the column was passed already, the TAB 
is ignored. 


Workstation: (n>0). The cursor is moved to column n of the 
current line, erasing passed-over characters (overwriting 
them with space characters). If the column was passed 
already, the TAB is ignored. 


In either case, if the tab position is greater than the line 
length indicated in the SELECT statement (always 8:0 
characters for the workstation), the print position advances 
to column 1 of the next line. If n is negative or zero, the 
TAB is ignored. 


8. COL(n) 


Like TAB, but does not erase any passed-over characters. 
(TAB and COL are equivalent for the printer, since 
characters cannot be erased.) 


9. AT(r, c[, [e]]) 


Printer: Ignored 


Workstation: AT(r,c[,[e]]) moves the cursor to row r, column 
c of the screen, and optionally erases e characters starting 
at (r,c). The following rules hold: 


a. l<=r<=24. 
b. 1<=c<=80. 


c. e>0; if e is greater than the number of characters 
from the cursor position to the end of the screen, 
only characters to the end of the screen are erased. 


d. If e and the preceding comma are omitted, no erasure 
occurs. If e is omitted but the preceding comma is 
included, the rest of the screen is erased, starting 
from (r,c). 


Note that AT, like COL, has no effect on passed-over 
characters. 


Syntax Examples: 


100 PRINT A$, BS 
200 PRINT USING 600, A, B, C 
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PUT Statement 


General Format: 


alpha-receiver 


GOTO line number 
| oara eae eee label \ 


PUT ‘oc \ [ LIUSING line number],arg[,arg] . . . 


where: 
exp 
arg = alpha-exp 
array-designator 


PUT inserts data into the record area or alpha-receiver using 
the Image (%) or FMT reference in the USING clause, if specified, or 
using standard format. 


PUT does not destroy values not explicitly overwritten. Data 
inserted into a record area with PUT can be written to the file by a 
subsequent WRITE or REWRITE statement. 


The DATA exit is taken if a data conversion error occurs. 


Syntax Example: 


10 SELECT #1 "EXAMPLE" CONSEC, RECSIZE=16 
20 OPEN #1 EXTEND, FILE="EXAMPLE", LIBRARY="DATA", VOLUME="VOL444" 


30 PUT#1,B$ 


NOTE 


PUT can be used to convert numeric data to a format 
acceptable to COBOL programs. See Appendix D for 


information on numeric data compatibility between BASIC 
and COBOL. 
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READ Statement 


General Format: 


READ receiver [receiver] . . . 


A READ statement causes the next available elements in a DATA 
list (values listed in DATA statements in the program) to be 
assigned sequentially to the receivers in the READ list. This 
process continues until all receivers in the READ list receive 
values or until all the elements in the DATA list are used. Each 
receiver must reference the corresponding type of data or an error 
results. 


The READ and DATA statements must be used together. If a READ 
statement references more receivers than the number of elements ina 
data list, the system uses the next DATA statement in statement 
number sequence. If there are no more DATA statements in the 
program, an error occurs and the program is terminated. 


The RESTORE statement resets the DATA list pointer, allowing 
values in a DATA list to be reused (see RESTORE). 


NOTE 


A DATA statement can occur anywhere in the program as 


long as it provides values in the correct order for the 
READ statement(s). 


Syntax Examples: 


100 READ A,B,C 
200 DATA 4,315,-3.98 


100. READ A$,N,B1$(3) 
200 DATA "ABCDE" ,27,"XYZ" 


100 FOR I=1 TO 10 

110 READ A(T) 

120 NEXT I 

200 DATA 7.2, 4.5, 6.921, 8, 4 
210 DATA 11.2, 9.1, 6.4, 8.52, 27 
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READ File Statement 


General Format: 


> 
KEYlexp1] {>= \ alpha-exp1 


READ file-exp L010 (1) \ 
RECORD =exp2 


line number 
[usa ae von arglarg] . .. 


GOTO line number GOTO line number 
| £00 ee {ne numb i |onra Jets eel ent 


where: 


HOLD = __holdrecord for REWRITE or DELETE. The record is held exclusively if in 
SHARED mode; i.e., no other user may access the record until REWRITE, 
DELETE, or anather READ HOLD is executed 


exp1 = alternate key number for keyed READ on alternate indexed file 
(primary key used if exp1 = O or is omitted) 


alpha-exp1 = _indexed file key specifier; the first record whose key satisfies the condi- 
tion is read. Only as many characters as specified in KEYLEN are com- 
pared; if the alpha-exp is shorter (defined length) than KEYLEN, only as 
many characters as its length are compared 


exp2 = —_ record number (from 1) for CONSEC files only 


line number line number or statement label of FMT 
USING statement = or lmage statement describing the input 
label data format 


= receiver 
ag = Meat, 


Data are moved (and optionally converted) into consecutive receivers 
EOD = end-of-data or invalid key exit, overriding the SELECT EOD 


DATA =~ dataconversion error exit 
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The READ File statement causes a record in a disk or tape file 
to be read. An OPEN statement must have already opened the file 
(see OPEN). 


If neither KEY nor RECORD is specified, the next consecutive 
record is read (using the established reference key in the case of 
alternate indexed files, that is, the last used in a READ KEY 
statement). 


If no argument list is present, the data are left unconverted in 
the record area, and are accessible only through GET. 


If USING is omitted, data are assumed to be in internal format. 
(See Subsection 8.4.7.) 


Syntax Example: 


SELECT #1 "EXAMPLE" CONSEC, RECSIZE=16 
OPEN #1 INPUT, FILE="EXAMPLE",LIBRARY="DATA" VOLUME="VOLUME" 
READ #1,B$ 


EI=131 


REM[ARK] Statement 


General Format: 


REMIARK] [text string] 


where: 
text string = any characters or blanks (except colons; a colon indicates the end of the 
statement) 


The programmer can use the REM statement to insert comments or 
explanatory remarks in the program. When the compiler encounters a 
REM statement, it ignores the remainder of the statement, but not 
necessarily the rest of the line, as the following examples (lines 
210 and 300) show. 


Syntax Examples: 


100 REM SUBROUTINE 

210 REM FACTOR: F=Y/(X+1) 

220 REM THE NUMBER MUST BE LESS THAN 1 
300 REM —--— :PRINT "ERROR":REM STOP:STOP 


The statements after the colon in line 210 and after the first 
and third colons in line 300 are executed. 


REM or REMARK are both acceptable statements. 
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RESTORE Statement 


General Format: 
RESTORE oxP = line number 

{me = statement label L exp] 
where: 


statement label program. If omitted, the first DATA statement is used 


le number \ = line number or statement label of a DATA statement in the 


1 <=exp <= total number of DATA items in the program, beginning at the given line, 
if specified. If omitted, default = 1 


The RESTORE statement allows READ statements to use DATA 
statements repetitively. When a RESTORE statement is encountered, 
the system resets the DATA pointer to the specified DATA value. A 
subsequent READ statement reads data values beginning with the 
specified value. 


When a RESTORE statement is encountered, the system resets the 
DATA pointer to the (expression) data value in the program, 
beginning either at the first DATA statement (if LINE = is omitted) 
or at the DATA statement at the specified line number or statement 
label. 


If expression is omitted, the pointer is set to the first data 
value in the program or in (or beyond) the specified DATA statement. 


The following program, for example, 


100 DATA 1,2,3 

200 DIM A(1,10) 

300 FOR I=1 TO 10 

400 IF I > =6 THEN RESTORE LINE=700, 3 
500 READ A(1,I) 

600 NEXT I 

700 DATA 4,5,6 

800 MAT PRINT A; 


produces the following output: 


123 4 5 6 6 6 6 6 


Syntax Examples: 


100 RESTORE 

200 RESTORE 5 

300 RESTORE (X-Y)/2 
400 RESTORE LINE = 
500 RESTORE LINE = 100, 3 


RETURN Statement 


General Format: 


RETURN 


The RETURN statement is used in a_ subroutine to- return 
processing of the program to the statement following the last 
executed GOSUB or GOSUB' statement. 


If a Program Function (PF) key was used to enter a marked 
subroutine, the RETURN statement returns control to the interrupted 
INPUT or STOP statement. 


Subroutines should not be entered repeatedly without executing a 
RETURN. Failure to return from these entries causes’ return 
information to be accumulated. This can eventually cause a stack 
overflow and premature termination of the program. (See RETURN 
CLEAR. ) 


Examples: 


100 GOSUB 300 

200 PRINT X:STOP 

300 REM THIS IS A SUBROUTINE 
400 — 

500 — 


900 RETURN:REM END OF SUBROUTINE 


100 GOSUB'03(A,B$) 

200 END 

300 DEFFN' 03(X,N$) 

400 PRINT USING 500,X,N$ 

500 % COST = $#, #44, #4+.44 CODE = #H+# 
600 RETURN 
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RETURN CLEAR Statement 


General Format: 


RETURN CLEAR [ALL] 


The RETURN CLEAR statement clears from memory the return-address 
information generated by the last executed subroutine call or by all 
executed subroutine calls. 


The RETURN CLEAR statement is a dummy RETURN statement. The 
RETURN CLEAR statement causes subroutine return address information 
from the last previously executed subroutine call to be removed from 
the internal tables. The program then continues at the statement 
following the RETURN CLEAR. 


If RETURN CLEAR ALL is’ specified, all subroutine return 
information is removed from the program stack. A RETURN or RETURN 
CLEAR cannot be executed before a subsequent GOSUB or GOSUB'. 


The RETURN CLEAR statement avoids memory stack overflow when a 
program repeatedly exits from subroutines without executing a 
RETURN. This is particularly useful when using the Program Function 
keys to control program execution (from either STOP or INPUT). When 
a PF key is used in this manner, a subroutine branch is made to the 
appropriate DEFFN' statement to continue execution. 


A subsequently executed RETURN statement causes the STOP or 
INPUT statement to be repeated automatically. However, the user may 
wish to continue a program without returning to the STOP or INPUT. 
In this case, the RETURN CLEAR statement should be used to exit from 
the DEFFN' subroutine. Executing a RETURN CLEAR statement when not 
inside a subroutine results in an error. 


Syntax Example: 


100 DEFFN'15 
200 RETURN CLEAR 
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REWRITE Statement 


General Format: 


REWRITE  file-exp [[,] SIZE = exp] [ L] MASK = alpha-exp1] 


line number 
[ov oe mi argharg]... 


GOTO line number 
|oara \ccee ean en) 


where: 
USING 2 line number — line number or statement label of 
statement label FMT or Image (%) describing the 


output format 
num-exp 
arg = alpha-exp 
array-designator 


DATA = _ data conversion error exit 


REWRITE is used to overwrite an existing record. The existing 
record must have been read with the HOLD option. 


If the argument list is omitted, it is assumed that a PUT 
statement formatted the record in the record area. If the argument 
list is present, it is converted value by value, using the Image (%) 
or FMT Statement (if specified). Otherwise, standard format is used. 


Direct concatenation operations within the REWRITE statement are 
illegal in VS BASIC. 


If the file is not an INDEXED VAR[C] file, the rewritten record 
size is the same as that of the overwritten record; SIZE and the 
implicit argument-list size are ignored. If the file is an INDEXED 
VAR[C] file, the size of the rewritten record is determined in one 
of the following ways: 

1. Record size = SIZE expression, if included. 


2. Record size = resultant size of the formatted argument list, 
if specified (see WRITE). 


__3.__If argument list omitted, the rewritten record is the same 
Size as the record it overwrites. 


REWRITE is not allowed for CONSEC VARC files. 
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MASK is used to set the alternate key mask for alternate indexed 
files. (See the explanation of the MASK function in Section 8.5 for 
more information.) If MASK is omitted, the alternate-key mask for 
the record is rewritten unchanged. 


Syntax Examples: 


100 REWRITE #1,SIZE=A ,MASK=MASK(#2), USING 300,A$,B,C% : 
200 DATA GOTO 1000 
300 FMT CH(20), PIC(##.#), PD(3) 
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RND Function 


General Format: 


RND (numeric exp) 


The RND (random number) function is used to produce a 
pseudorandom number between 0 and 1. The term "pseudorandom" refers 
to the fact that BASIC cannot produce truly random numbers. 
Instead, it relies on an internal algorithm that uses the last 
random number to generate the next one. The resulting sequence 
(list) of values, though obviously not truly random, is scattered in 
the range zero to one in such a manner as to appear to be 
statistically random. 


There are three ways to use RND(exp), based on the value of the 
argument: 


1. exp <0 or exp >1 -- produces the next pseudorandom number in 
the list as produced by the internal algorithm. If this is 
the first use of RND in the program, the compiler sets the 
previous value at compilation. 


2. QO<exp <1 -- returns exp as the result and resets the list to 
this value. 


3. exp =0 -- similar to Option 2, but produces a number 
computed from the time of day when the RND is executed, 
rather than from a user- or compiler-specified value. 


See Section 2.6 for more information on RND. 


Examples: 


100 A=RND(.5) 

200 B=RND(2) 

300 C=RND(1) 

400 PRINT "A=";A,"B=";B,"C=";C 


Result: A=.5 B=.259780899273209 C=.298807370711264 
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ROTATE[C] Statement 


General Format: 


ROTATEIC] (alpha-receiver, numeric exp) 


where: 
-8 <= numeric exp <= 8 


This statement rotates bits in the given alpha-receiver. If the 
expression is less than zero, rotation is left to right. If 
expression is greater than zero, rotation is right to left. Bits 
that are moved past one end of the receiver are moved to the other 
end of the receiver. 


If C is not specified, rotation occurs for each byte in the 
receiver. If C is specified, the entire receiver is rotated. 


ROTATE operates on the defined length of the alpha-receiver. 


Examples: 


100 DIM A$5 
200 A$ = HEX(345678AD) 
300 ROTATE (A$,4) 
400 PRINT HEXOF(A$) 
Result: 

436587DA02 


500 ROTATE C (A$,-8) 
600 PRINT HEXOF (A$) 


Result: 


02436587DA, assuming the previous result 
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ROUND Function 


General Format: 


ROUND (exp,exp) 


ROUND(X,N) is equivalent to the expression: 
SGN (X) * (INT (ABS (X) *10**N%+0.5)/10**NZ%) 


Its effect is to round off the value of X to the precision specified 
by N. If N is positive, X is rounded off to N decimal places. If N 
is negative, X is rounded off to the Nth place to the left of the 
decimal point. If N is not an integer, it is truncated. 

For example: 


Numeric Examples: 


ROUND (123.4567,4) = 123.4567 
ROUND (123.4567,3) = 123.4570 
ROUND (123.4567,2) = 123.4600 
ROUND (123.4567,1) = 123.5000 
ROUND (123.4567,0) = 123.0000 
ROUND (123.4567,-1) = 120.0000 
ROUND (123.4567,-2) = 100.0000 
ROUND(123.4567,-3) = Q_ ete. 


Unlike the INT function, the ROUND function rounds upward. For 
example, rounding 4.7 to 0 decimal places produces 5 with the ROUND 
function, but 4 with the INT function. 


Syntax Example: 
100 Y = ROUND(X,5) 
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SEARCH Statement 


General Format: 


SEARCH [-]alpha-exp1 < | 7 > alpha-exp2 


To numeric array-designator [STEP numeric exp] 
alpha-receiver 


SEARCH searches alpha-expl (defined length) for substrings of 
the same length as alpha-exp2 (actual length) that satisfy the given 
relation. 


If "-" is not specified, the SEARCH begins with the substring 
starting at the leftmost byte (byte 1) of alpha-expl; each 
subsequent substring checked has a starting byte n bytes to the 
right of the previous substring, where n is the value of the STEP 
expression. 


If "-" is specified, the SEARCH begins with the rightmost 
substring, that is, starting at the (defined length alpha-expl minus 
actual length alpha-exp2 +1)th byte of alpha-expl. Subsequent 
substrings have a starting byte n bytes to the left of that of the 
previous substring. 


If STEP is omitted, n=l and all substrings are checked. 


SEARCH terminates when it runs out of substrings of the proper 
length or reaches the limit of the TO argument. If expl is 
initially too short, no substring is checked. 


Upon completion, the TO argument contains the starting positions 
of the substrings found (from 1) in one of the following formats: 


1. If "numeric array-designator", the array contains’ the 
numeric starting positions in the order in which they were 
found. The first unused array element (if any) contains 0. 
Any other unused elements remain unchanged. 


2. If "“alpha-receiver", each pair of bytes contains the 2-—byte 
binary representation of the starting positions, as in 
Option 1. The first unused pair of bytes (if any) will 
contain binary 0. Any other unused bytes remain unchanged. 
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In either case, if the array or receiver is too short to contain all 
positions found, the remaining positions are lost. 


Example: 


100 DIM A$40, N(1,8) 

200 A$="SESSIONS OF SWEET SILENT THOUGHT" 
300 SEARCH A$=STR(A$,1,1) TO N() 

400 SEARCH -A$=STR(A$,1,1) TO BS 

500 PRINT HEXOF(B$) 

600 MAT PRINT N 


Output: 
0013000D000800040003000100002020 
1 3 4 8 
13 19 0 0 
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SELECT Statement 


General Format: 


SELECT select-elt [,select-elt] [...] 


where: 

PAUSEId] 

RADIANS 
DEGREES 

= GRADS 
select-elt = PRINTER [(exp)] 

CRT 
WS 
POOL file numberl,file number] . . . BLOCKS =int 


PAUSEld] d/10 second execution pause after each write to the 
workstation. If d=O or is omitted, no pause. System 
default = no pause. d must be an integer. 


DEGREES respectively. (360 degrees = 2 radians = 400 grads.) 


orcrees| trig arguments/results in radians, degrees or grads, 
GRADS System default = radians. 


CRT 
WS 


line printer or workstation, as specified. If no 
SELECT has been executed, output is routed to 
the workstation by default. 


{ern route print output (PRINT, PRINTUSING, etc.) to the 


exp can be used following PRINTER to specify 
nonstandard printer line width, where 1 < = exp < = 162 
(if omitted or invalid, default = 132). 


POOL a buffer pool for the specified files. (Files must 
be indexed) 


BLOCKS the number of 2048-byte buffers in the pool. 


int an integer from 1 to 255. 


The SELECT statement allows the programmer to define a number of 
programming options. The SELECT statement can set the length of 
time the workstation pauses after each write, the units for 
trigonometric calculations, the output device for PRINT and related 
statements, and/or buffer-—pooling options. 
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A POOL specification can only appear after the SELECT File 
statements for the pooled files, and a particular file-number can 
only be included in a single POOL. Only indexed files opened in 
INPUT or IO modes can be pooled. Otherwise, this statement can be 
used anywhere and as often as_ desired. The select-elts are 
processed one at a time, from left to right. 


Syntax Example: 
100 SELECT PAUSE 9, PRINTER, DEGREES , POOL#1 ,#2 ,BLOCKS=2 
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SELECT File Statement 


General Format: 


Consecutive 


SELECT file-number [] “prname”L] =a LIOERR exit] 
Printer 


where: 
File-number = #n, where n is an integer from 1 to 64 


prname = 1 to 8 characters (alphanumeric, including @,#,$) 
Consecutive = [VARIC][,]] CONSEC, RECSIZE = int1LEOD exit] 
Indexed = [VARIC][,]] INDEXED, RECSIZE = int1, KEYPOS = int2, 


KEYLEN = int3 f ogee orspectatapec..J LEOD exit] 


alt-spec = KEY int4, KEYPOS = int5, KEYLEN = int6 [,DUP] 
int4 = 1 to 16, may not be repeated. 


IL 
Tape = [VARICIL]] TAPE, {ne} * | RECSIZE = int7, BLKSIZE = int8, 
AL 


800 
DENSITY = < 1600 ?LEOD exit] 
6250 


Printer = PRINTER, RECSIZE = int10 
ie GOTO line number 

GOSUB statement label 
IL = IBM-Labelled Tapes 


NL = Non-Labelled Tapes 
AL = ANSI-Labelled Tapes 


SELECT file specifies the characteristics of a file that is to 
be opened (see the OPEN statement) and read from and/or written to 
(see READ, WRITE, REWRITE, GET, PUT, DELETE, and SKIP). 


SELECT can specify four types of files: 
1. Consecutive disk files -- Files that can only be read or 


written to sequentially. READ, WRITE, REWRITE, GET, PUT, 
and SKIP can be used. 
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Indexed disk files -- Files indexed with a key field. The 
key length and position must be specified. Alternate keys 
can also be specified. Records can be accessed sequentially 
or by a specific key. READ, WRITE, REWRITE, GET, PUT, 
DELETE, and SKIP can be used. 


Tape -—— Files can be read from or written to a tape. READ, 
WRITE, GET, PUT, and SKIP can be used. 


Printer --— Files can be written for output to the printer. 
The first two bytes in each record must be printer control 
characters (see the VS Principles of Operation). Only WRITE 
and PUT can be used, and only OUTPUT mode can be used in the 
OPEN statement. 


The SELECT statement sets up a user file block (UFB) of file 
information and a record area for the specified consecutive, 
indexed, tape, or printer file, referenced by the file number, with 
the supplied parameters used to set initial values in the UFB. 


A file number cannot appear in more than one SELECT statement. 
All SELECT statements must appear before any file I/O statements in 
the program. 


SELECT statement parameters are described as follows. 


file-number -- Pound-sign (#) followed by an integer from l 
to 64, inclusive. This file-number is used in all other I/0 
statements to refer to the file specified by this SELECT 
statement. 


prname -- Literal string consisting of 1 to 8 alphabetic or 
numeric characters, including $, #, and @. This is the 
external name used by the operating system to access the 
file and to prompt the user for file information. 

VAR[C] -- Variable-length [optionally compressed] records. 
Neither VAR nor C need be set for any existing file, but 
they must be set for a file to be created (output mode) with 
variable-length (or compressed) records. 


RECSIZE -- Record size for fixed-length files; maximum 
record size for variable-length files. 


Limits: 
CONSEC -- 1<=int1<=2048 
VAR CONSEC --— 1<=int1<=2024 
INDEXED —— 1<=int1<=2040 


VAR INDEXED -—— 1<=int1<=2024 
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KEYPOS —~ Key position in record (from 1) for indexed files. 


KEYLEN --— Key length (maximum = 255) for indexed files. 


IOERR -—- Branch taken if I/O error occurs on the selected 
file. 
EOD -- Branch taken if end-of-data, invalid key, or 


duplicate key on an I/O operation not having an EOD exit of 
its own. 


ALTERNATE KEY, KEYPOS, KEYLEN, DUP (Duplicate Key values 
allowed) -- Key number, position, and length for. one 


alternate key. This applies to indexed files that allow up 
to 16 alternate key access paths. For an existing file, the 
ALTERNATE key list either can be omitted or a subset of the 
existing alternate key structure. The key numbers specified 
must be identical to those used when creating the file. 
Alternate keys that are not included are not accessible by 
either READ or the KEY() function. 


Syntax Examples: 


100 
200 


300 


400 
500 


600 
700 


800 


SELECT #1,"HEAP",VAR,CONSEC,RECSIZE=100,EOD GOTO 1000 ! 
IOERR GOSUB 200 


SELECT#2 , "OF" , CONSEC . RECSIZE=50 


SELECT#3 , "BROKEN" , INDEXED , RECSIZE=200 ,KEYPOS=1,KEYLEN= ! 
10,ALT KEY1,KEYPOS=11,KEYLEN=10 ,KEY2 , KEYPOS=21 ,KEYLEN=10 


SELECT#4" IMAGES", VAR, TAPE,NL,RECSIZE=15, BLKSIZE=1000 ! 
DENSITY=1600,EOD GOSUB 1000 


SELECT#5 , "WHERE" , PRINTER , RECSIZE=134 
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SGN Function 


General Format: 


SGN(numeric exp) 


The SGN function returns an integer value equal to -1l if the 
argument is less than zero, 0 if the argument equals zero, or +1 if 
the argument is greater than zero. 


syntax Examples: 


100 Y = 
200 Z = SGN(-5) 


Numeric Examples: 


SGN(5) = 1 
SGN(-5) = -l 
SGN(0) = 0 
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SIN Function 


General Format: 


SIN(numeric exp) 


The SIN function returns a floating-point value that is the sine 
of the numeric expression specified as its argument. The expression 
is calculated in units of radians, degrees, or grads, depending on 
the trigonometric mode specified by the most recently executed 
SELECT statement. If no SELECT statement was executed in the 
program or subprogram, the default mode is radians. 


Syntax Example: 


100 Y = SIN(X) 


Numeric Example: 


SIN(O) = 0 
SIN(90) = 1 (assuming the calculation is performed in degrees) 
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SIZE Function 


General Format: 


SIZE (file-exp) 


SIZE returns the size in bytes of the last record read from the 
specified file. The result is an integer. 


Syntax Example: 
100 Y = SIZE(#1) 
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SKIP Statement 


General Format: 


: [BEG GOTO line number 
SKIP file-exp ee | £00 Sa3e} ees na 


where: 
num-exp = number of records to skip; forward if n>0O; backward ifn < O 
BEG = skip to beginning of file 


SKIP positions a CONSEC file forward or backward a given number 
of records, or to the beginning (BEG) of the file. The EOD exit is 
taken if a SKIP results in a position before the beginning or past 
the end of the file. For example, if record 1 was just read, 
SKIP#n,;2 causes the next record read to be record 4. SKIP #n,-1 
causes the same record to be reread by the next READ or GET 
statement. A SKIP value of 0 is ignored. 


Syntax Examples: 


100 SKIP #A,BEG 
200 SKIP #1,B,EOD GOTO 1000 
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SOR Function 


General Format: 


SOR (numeric exp) 


The SOR function returns a floating-point value that is the 
square root of the numeric expression specified as its argument. 


Syntax Example: 
100 Y = SOR(X) 


Numeric Example: 


SOR(4) = 2 
SOR(16) = 4 


IT-152 


STOP Statement 


General Format: 


STOP l[alpha-exp] 


The STOP statement interrupts program execution. When STOP is 
encountered, STOP and the given alpha-expression are printed at the 
workstation. 


Execution can be continued in either of two ways: 


1. ENTER continues execution at the next executable statement 
foilowing the STOP statement. 


2. Pressing a PF key corresponding to a marked subroutine 
causes the program to continue at the entry point of the 
subroutine. A corresponding RETURN causes the STOP to 
execute again. 


The execution of STOP is exactly like that of INPUT with no 
arguments in that the program waits for operator response. This 
applies to the use of PF keys for DEFFN' strings and subroutine 
entry. Although data cannot be entered directly into a variable 
from STOP, data can be passed to the arguments of a DEFFN' 
subroutine. 


Syntax Examples: 
100 STOP 


200 STOP A$ 
300 STOP "TWAS BRILLIG AND THE SLITHEY TOVES" 
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STR Function 


General Format: 


STR( ope \ L fs] Ln) 1) 


alpha array string 


where: 
s = starting character in substring (an expression) (1 if omitted); cannot be zero or 
negative 
number of consecutive characters desired (an expression); cannot be zero or 
negative 


The string function, STR, specifies a substring of an alpha 
variable or array string. With it, a portion of an alpha value can 
be examined, extracted or changed. For example, the statement 


100 B$=STR(A$,3,4), 


sets the receiver B$ equal to the third, fourth, fifth, and sixth 
characters of A$. 


If n is omitted, the remainder of the alpha value is used, 
including trailing spaces. 


Any attempt to create a substring of length zero results in a 
run-time cancel message. 


The STR function can also be used as a receiver on the left side 
of an assignment (LET) statement to assign a value to a substring. 


Example: 


100 A$=""ABCDEF" 
200 STR(A$,4,3)="XYZ" 
300 PRINT A$ 


Output: ABCXYZ 


If the STR function is used on the left side of an assignment 
(LET) statement, and the value to be received is shorter than the 
specified substring, the substring is filled with trailing spaces. 
In this case, the first argument of the STR function must be an 
alpha receiver. 
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SUB Statement 


General Format: 


SUB “name” [ [ADDR] (arg[,arg} . . .)] 


statements in subroutine 


where: 
“name” = name of subroutine (1 to 8 alphabetic or numeric characters; first alphabetic, 
including @,#, and $) 


alpha scalar variable 
numeric scalar variable 
array-designator 
file-number 


SUB defines a subroutine with (or without) an argument list. 
(The SUB statement and use of external subroutines are discussed in 
Section 6.5.) Its logical end is signalled by an END statement, 
just as in a main program. The optional return code is ignored by 
the BASIC calling program. SUB must be the first statement, other 
than REM, in the program. 


The name specified in the SUB statement need not be the same as 
the object file name. Subroutines must be linked to their calling 
program prior to run time; a CALL statement in the calling program 
initiates a branch to the beginning of the subprogram. 


The optional ADDR syntax specifies the type of address list that 
the SUB routine expects to be passed to it to locate the passed 
arguments. This is explained in more detail in Subsection 6.5.4. 


Generally, when dealing entirely with BASIC 
programs/subprograms, ADDR should not be used. It usually should be 
used if the BASIC subroutine is being called from a non-BASIC (e.g., 
COBOL) subroutine. 


Variables and arrays local to the subroutine (i.e., not in the 
argument list) obey the usual rules. However, they are initialized 
only on the first subroutine call; on subsequent calls, they retain 
their previous values and dimensions. 
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The file number argument, used in file I/O statements, is 
logically replaced by the passed file number or file-expression when 
CALL is executed. The file number refers to SELECT and other I/O 
operations executed in the main program. Dummy file numbers cannot, 
therefore, appear in SELECT statements in the subroutine. When a 
file number is received as a parameter, a SELECT statement for that 
file number in the subroutine is not permitted. However, local file 
numbers can be used to set up (SELECT) an I/O area local to the 
subroutine, independent of and inaccessible to the calling program. 


Other arguments are passed as follows: 


1. Non-ADDR Form -- The type (matrix, vector) of all array 
arguments must be specified for correct argument passing to 
occur. This can be done in either of two ways: 


a. In one or more DIM statements occurring before the use 
of any of the dummy arrays. The dimensions specified 
are of no significance; the program notes only the 
vector-matrix distinction. 


b. If not in a DIM statement, the array is assumed to be a 
matrix. 


Arrays and receivers are not physically moved; the 
subroutine receives pointers to their locations’ and 
dimensions. Thus, changed values and array dimensions (MAT 
REDIM) can be returned to the calling program. 


Expressions and alpha-expressions that are not receivers 
must be created in temporary locations by the calling 
program; otherwise, pointers to their locations (and 
lengths, for alpha-expressions) are passed to the subroutine 
as in (a). Although values may be changed in the 
subroutine, the calling program does not have access to the 
new values. 


In either case, the defined dimensions and lengths received 
by the subroutine specify the maximum area, as in a DIM or 
COM. MAT REDIM can change these dimensions (subject to the 
usual rules) and, as indicated, these new dimensions are 
retained upon return to the calling program. 


2. ADDR Form -- SUB passes pointers to the locations of the 
passed arguments. All array dimensions and alphanumeric 
lengths are as specified in the SUB program (or are the 
default values). 


Otherwise, the ADDR form is the same as the non-ADDR form. 
Specifically, any changes to the data are reflected in the 
calling program upon return from the subroutine. MAT REDIM 
has no effect outside the subroutine, however, because the 
dimensioning information from the calling program is 
inaccessible to the called subprogram. 
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No subroutine dummy argument can have the same name as another 
dummy argument of the same type (scalar/array), or as a COM argument 
specified in the subroutine. 


A subroutine can call other subroutines, but cannot call itself. 


A source file can contain exactly one module, which can be 
either a program or a subroutine. 


Examples: 


100 SUB "AND" 

200 A$ = STR("THE DRY STONE NO",5,3) 
300 PRINT A$' "SOUND OF WATER" 

400 END 


100 SUB "ONLY" ADDR(A$,B,BC(),#N) 
200 IF A$ AND "THERE IS A SHADOW" THEN B=20 
300 END 


100 SUB "123456" (A$) 


100 PRINT A$ 
300 END 
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TAN Function 


General Format: 


TAN (numeric exp) 


The TAN function returns a floating-point value that is the 
tangent of the numeric expression specified as its argument. The 
expression is in units of radians, degrees, or grads, depending on 
the trigonometric mode specified by the most recently executed 
SELECT statement. If no SELECT statement was executed in the 
program or subprogram, the default mode is radians. 


Syntax Example: 
100 X = TAN(Y) 


Numeric Examples: 


TAN(O) = 0 
TAN(45) = 1 (assuming the calculation is performed in degrees) 
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TIME Function 


General Format: 


TIME 


TIME returns an 8-character string containing the current time 
(accurate to hundredths of a second) in the form HHMMSShh. 


Syntax Example: 
100 A$ = TIME 
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TITLE Compiler Directive 


General Format: 


TITLE [exp] 


The TITLE statement is a compiler directive (see Subsection 
2.4.2). A TITLE statement must be the only statement on a line. 
When a TITLE statement is encountered during compilation, the 
compiler skips to the top of the next page of output listing and 
prints the expression in the TITLE statement. The same title 
appears on all subsequent pages of the listing until another TITLE 
statement occurs in the program text. 


TITLE statements cannot be continued, nor can they be used ina 
multiple statement line. 


Example: 
100 TITLE PART I: VARIABLE INITIALIZATION SECTION 


When this statement is encountered, the title 
PART I: VARIABLE INITIALIZATION SECTION 


appears at the top of the page of source listing. 
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TRAN Statement 


General Format: 


TRAN (alpha-receiver, alpha-exp) [REPLACING] 


TRAN translates (in place) the alpha-receiver, using the 
alpha-expression as a translate table or list. 


The 


defined length of the alpha-receiver is translated left to 


right, one byte at a time, as follows: 


1. The alpha-expression (translate table) is moved to a 
separate location; thus, it cannot be affected by the 
translation. 

2. Each byte is translated, in one of the following ways: 

a. REPLACING specified: The alpha-expression is treated as 

a list of consecutive byte pairs, ending either at a 
HEX(2020) pair or at the end (last full byte pair) of 
the alpha-expression. The second byte of each pair is a 
“translate from" byte, and the first is a "translate to" 
byte. 
The alpha-expression is searched from left to right 
until a “translate from" matching the subject byte is 
found. The subject byte is then changed to the 
corresponding "translate-to" character. If a matching 
byte is not found, the subject byte is not changed. 

b. REPLACING not specified: The alpha-expression is 
treated as a table of consecutive "translate to" bytes. 
The subject byte is changed to the (n+l)th byte in the 
table, where n is the hex value of the subject byte. If 
the alpha-expression has fewer than n+l bytes, the 
subject byte is not changed. 

Example: 

100 AS="JOHN" 

200 B$=HEX(00010203) 

300 TRAN(A$,"MJAORHYN" ) REPLACING 

400 TRAN(B$,"ABCDEF" ) 

500 PRINT A$,BS$ 

Output: 

MARY ABCD 
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UNPACK Statement 


General Format: 


UNPACK PIC (image) alpha-expression TO 


numeric array-designator , ) Numeric array-designator 
numeric variable numeric variable f: 


where: 
image = [+][#.. JLI[#.. JIT TTT] (atleast 1 #) 


The UNPACK statement is used to unpack numeric data that was 
packed by a PACK statement. Starting at the beginning of the 
specified alphanumeric expression, packed numeric data are unpacked, 
converted to internal floating-point values, and stored into the 
specified numeric variables or arrays. The format of the packed 
data is specified by the image (see PACK); thus, the same image that 
was used to pack the data should be used in the UNPACK statement. 
An error results if the UNPACK statement attempts to unpack more 
numeric values than can exist in the alphanumeric expression 
(defined length used). 


Syntax Examples: 


100 UNPACK PIC (###+)A$ TO X,Y,Z 

200 UNPACK PIC (+#.##)STR(A$,4,2) TO X 
300 UNPACK PIC (+#.## JAS() TO N() 

400 UNPACK PIC (######)A$() TO X,Y,N(),M() 


Example: 


100 X=24:DIM A$3 

200 PACK PIC (####)A$ FROM X 
300 PRINT X 

400 PRINT HEXOF (A$) 

500 UNPACK PIC (####)A$ TO Y 
600 PRINT A$,Y 


Output: 
24 


002420 
5 24 
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SUNPACK Statement 


General Formats: 


$PACK [ i{ aM alpha-exp) | alpha-receiver FROM argl[,arg] ... 


GOTO line number 
| ara Noone ue on 
where: 


line number = line number or statement label of 
statement label data conversion error exit 


exp 
arg= < alpha-exp, EXCEPT alpha array string 
array-designator 


$SUNPACK |( {ez} alpha-exp) | alpha-exp TO argLarg]... 


GOTO line number 
| oara ee { statement label M 
where: 
arg = ese EXCEPT alpha array — 


array-designator 


See $PACK for explanation of syntax. 


IIT-163 


VAL Function 


General Format: 


VAL (alpha-expI,d]) 


where: 
d = 1,2,3,4 (default = 1) 


The VAL function is the inverse of the BIN function. It 
converts the first d characters of the specified alphanumeric value 
to an integer. VAL can be used wherever numeric functions are used 
normally. (See Section 5.6.) 


VAL is particularly useful for code conversion and table 
lookups, because the converted number can be used as a subscript to 
retrieve the corresponding code or data from an array, or to 
retrieve codes or information from DATA statements. 


Syntax Examples: 


100 X=VAL(A$) 

200 PRINT VAL("A") 

300 IF VAL(STR(A$,3,1) 80 THEN 100 
400 Z=VAL(A$)*10-Y | 
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WRITE Statement 


General Format: 


WRITE file-expI[[, ]SIZE=exp][L,] MASK = alpha-exp 1] 


line number 
[29K etn | argLargl .. 
GOTO line number GOTO line number 
Ee yoru — ial | para jereey eee coat 


where: 
SIZE = record size for VAR files. 


MASK = 2-byte mask alternate index mask for alternate indexed 
files. (If only 1 byte, right-padded with HEX(00)) 


USING ee number \ _ line number of Image or FMT 


statement label describing formatting to be used 


on the output data 
If USING is omitted, internal format is used. 
exp 
arg = < alpha-exp 
array-designator 


EOD = duplicate-key exit; overrides the SELECT EOD 


DATA = data conversion error exit (formatting error) 


WRITE writes the next sequential record to a CONSEC file 
(OUTPUT, EXTEND, or SHARED mode), or a keyed record to an INDEXED 
file (I0, OUTPUT, or SHARED mode). The WRITE statement is also 
discussed in Section 8.4. 


If an argument list is present, the data are moved one value at 
a time, using the format specified by Image (%), FMT, or internal 
formatting. If an argument list is not present, the data are taken 
directly from the record area, where they were already formatted 
with a PUT statement. 


Direct concatenation operations within the WRITE statement are 
illegal in VS BASIC. 


For non-VAR[C] files, the record size is as specified in SELECT; 


the SIZE parameter is ignored. For VAR[C] files, the record size is 
determined in one of the following ways: 
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1. Record size equals SIZE expression, if specified. 


2. If an argument-list is present, record size equals’ the 
resulting formatted record size. If USING is omitted, the 
data are left in internal format, with record size equal to 
the sum of individual sizes: 


floating-point = 8 bytes 
integer = 4 bytes 
alphanumeric = defined length 


3. If no argument-list is present, then the record size is 
identical to that of the last record read or written, if 
any, or to the maximum RECSIZE. 


For alternate indexed files, MASK is used to set the alternate 


key mask for the record (see the description of the MASK function in 
Section 8.5). If omitted, the current MASK is used. 


Syntax Example: 
100 WRITE #N,SIZE=100,MASK=A$,EOD GOTO 1000,DATA GOTO 1200 
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XOR Statement 


General Format: 


[LET] alpha-receiver = [logical exp] XOR logical exp 


logical exp: see Section 5.7 


The XOR operator performs a logical exclusive OR on two or more 
alphanumeric arguments. 


If the operand (logical expression) is shorter than the 
receiver, the remaining characters of the receiver are left 
unchanged. If the operand is longer than the receiver, the 
operation stops when the receiver is filled. (See Section 5.7 for 
more information on logical expressions.) 


Syntax Example: 
100 Y$ = HEX(00) XOR HEX(AA) 


Numeric Examples: 


HEX (0000)=HEX(OFOF) XOR HEX(0OFOF) 
HEX (OFFO)=HEX(OOFF) XOR HEX(OFOF) 
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APPENDIX A 


VS BASIC RESERVED WORDS 


"When I use a word, it means just what I 


choose it to mean--— neither more nor less." 


-- H. Dumpty, 
Through the Looking-Glass 


This appendix contains a list of all VS BASIC reserved words. 
Reserved words have a specific meaning to the BASIC compiler as 
statement verbs and keywords, and cannot be used either as variable 


mames or as statement labels. 


Some words on this list are not 


documented in this manual, since they are reserved for features to 
be implemented in future versions of the BASIC compiler. 


$PACK 
ADDR 
ARCCOS 
BEG 
BLKSIZE 
BOOL3 
BOOL9 
BOOLF 
CLEAR 
CONSEC 
CURSOR 
DEF FN 
DISPLAY 
ELSE 


SUNPACK 
AL 
ARCSIN 
BELL 
BLOCKS 
BOOL4 
BOOLA 
BRIGHT 
CLOSE 
CONSTANT 
DATA 

DEF FN' 
DO 

END 

FAC 

FMT 

FROM . 
GOTO 
HEXPRINT 
INDEXED 
INV 
KEYPOS 
LINE 

MIN 
NODISPLAY 
ON 

PAGE 
PRINT 
READ 
REMARK 


ABS 

ALL 
ARCTAN 
BI 

BOOL 
BOOL5 
BOOLB 
BY 

COL 
CONVERT 
DATE 
DEGREES 
DPACK 
ENTER 
FILE 

FN 

FS 

GRAD 


-HEXUNPACK 


INIT 

IO 

KEYS 
LOG 

MOD 
NOGETPARM 
ONLY 
PAUSE 
PRINTER 
REAL 
REPEAT 


ACCEPT 
ALT 
ASORT 
BIN 
BOOLO 
BOOL6 
BOOLC 
CALL 
COM 
COPY 
DECIMAL 
DELETE 
DSORT 
EOD 
FILESEQ 


PD 
PROTECT 
RECORD 
REPLACING 


ADDC 


REWRITE 
SEARCH 
SIZE 

STOP 

TAN 

TO 
UPPERCASE 
VARC 

XxX 


ROTATE 


TRN 
VALIDATE 
WRITE 
ZERO 


ROUND 
SHORT 

SOR 

TAB 
TIMEOUT 
UNDERLINE 
VALUE 

WS 


SCREEN 
SIN 
STEP 
TABLE 
TITLE 
UNPACK 
VAR 
XOR 


APPENDIX B 
VS BASIC COMPILER OPTIONS 


The VS BASIC compiler provides the following options. 
SOURCE 


If SOURCE = YES, the compiler produces a source listing of the 
compiled program, with accompanying diagnostics. If SOURCE = NO, 
the compiler does not produce a source listing. (Diagnostics are 
produced if either SOURCE, PMAP, XREF, or ERRLIST is specified.) 


PMAP 


If PMAP = YES, the compiler produces a PMAP (program map) for 
the compiled program. A PMAP contains the machine instructions 
generated by each BASIC verb, with the address of each instruction, 
as well as a map of the static area showing the values and locations 
of all data items. A PMAP consists of five basic columns: 


Column 1 — BASIC verbs and line numbers. 

Column 2 — Address and object code. 

Column 3 — Assembler instructions. 

Column 4 — Operands for instructions, hex codes for literals. 
Column 5 — Comments. 


If the program contains common variables (i.e., listed in a COM 
statement), a map of the common area follows the PMAP, beginning 
with *COMMON on a new page. In the common area map, the columns 
serve the same purpose as in the PMAP, except for the first column. 
The first column of the common area map contains only ¥*COMMON at the 
beginning of the map. If there is no common area, a map of the 
static area immediately follows the PMAP, beginning with the word 
STATIC in column 1 on a new 


page. 


In the static area map, the columns serve the same purpose as in 
the PMAP, with the exception of the first column. The first column > 
contains either *STATIC, indicating the address of the contents of 
the static section following, or *PGT (Program Global Table) 
indicating the address of the information in the table following. 
The static section contains variables, while the PGT contains such 
data items as subroutine addresses and other constants. 


XREF 


The XREF (cross-reference) listing consists of five parts: 


1. A listing of line number references (column one) and the 
line numbers that reference them (following columns). 


2. A listing of the variable names, their lengths (alpha only), 
and, for arrays, their dimensions (all in column one). Each 
variable is followed by the location of the variable's 
storage area (or, for arrays, the descriptor and data area) 
on the same line, and the line numbers that reference the 
variable (on succeeding lines). 


3. A listing of user-defined functions and the line numbers 
that reference them. 


4. A listing of BASIC functions referenced, and the line 
numbers that reference them. 


5. A listing of DEF FN' subroutines contained within the 
program and the line numbers that reference them. 


LOAD 


If LOAD = YES, the compiler creates an object program in VS 
object program format, and stores it in an output file. If LOAD = 
NO, the compiler does not create an object program and does not 
display an output definition screen to name the output file. 


SYMB 


If SYMB = YES, the compiler inserts symbolic debug information 
in the object program. If SYMB = NO, the compiler does not insert 
this information, and the symbolic debug facility cannot be used to 
debug the object program at run time. 


SUBCHK 


If SUBCHK = YES, the compiler generates special code that checks 
the ranges of subscripts during program execution, and causes a 
program cancellation (execution interruption) if a subscript exceeds 
its defined limit. Otherwise, no check is performed on subscripts 
during execution. 


B-2 


DFLOAT 


If DFLOAT = YES, the compiler uses the float decimal 
representation for all floating-point operations in this module. 
Since float decimal support is not available on VS-80 and VS-50 
systems, a response of YES on VS-80 and VS-50 systems generates an 
immediate error message. The default response, NO, instructs the 
compiler to the float binary representation for all floating-point 
operation in this module. 


ERRLIST 


If ERRLIST = YES, a listing of the compiler diagnostics is 
produced. 


FLAG 


The FLAG option specifies the lowest level of error severity 
that causes the compiler to print a diagnostic message. Any error 
with a severity code greater than or equal to the specified FLAG 
value causes the compiler to print a diagnostic message. 


STOP 

The STOP option specifies the lowest level of error severity 
that causes the compiler to abort the compilation. Any error with a 
severity code greater than or equal to the specified STOP value 
terminates the compilation (no object program is produced). 


LINES 


The LINES option sets the number of lines per page for all 
compiler—produced printouts. 


APPENDIX C 
FLOATING-POINT AND INTEGER CALCULATIONS 


C.1 INTRODUCTION 


VS BASIC supports two numeric formats: integer and floating— 
point. In addition, the programmer can choose one of two floating-— 
point representations: float binary or float decimal. Each format 
has unique features and limitations that make it suitable for some 
applications and unsuitable for others. Chapter 3 compared the 
speed and precision of the numeric formats in a general sense; this 
appendix provides a more detailed description of the advantages and 
disadvantages of each format. 


C.2 INTEGER FORMAT 


Integer calculations are precise and consistent for a limited 
range of values. On the VS, the range is from -2,147,483,648 to 
2,147,483 ,647. Except for the occurrence of integer overflow, 
standard integer operations (including arithmetic and relational 
operators) produce the expected results and obey standard 
mathematical laws, such as those concerning associative and 
commutative operations. For example, integer equality ("=") tests 
for exact equality, and it is easy to understand when two integers 
are exactly equal. 


Integer variables should be used whenever precise results are 
required and the expected range of values falls within the limited 
range supported by VS BASIC. 


C.3 FLOAT BINARY FORMAT 

The float binary format can represent the largest range of values 
(+ 5.4 x 10°7° to + 7.2 x 10’°) of all numeric formats. Float 
binary calculations are slower than integer calculations, but are 
faster than those performed in float decimal. Float binary 
operations, however, are the least precise of operations on the 
numeric data types. 


Float binary operations lose precision when the _ internal 
hexadecimal representation (refer to Chapter 3) is converted to or 
from the decimal representation. The conversion can result in a 
loss of precision because a one-to-one correspondence does not exist 
between hexadecimal and decimal fractions. For example, the decimal 
fraction 0.2 converts to a repeating hexadecimal fraction of 
0.33333... The float binary format cannot exactly represent decimal 
0.2 in a finite number of digits; operations on the exact decimal 
value 0.2 manipulate the hexadecimal approximation 0.33333333333333 
rather than 0.333... 


In most cases, the loss of precision in a 14-digit floating- 
point value is not significant. The VS BASIC input/output routines 
(PRINT, ACCEPT, INPUT, etc.) automatically perform the 
interconversions of numeric data between the decimal form shown in 
ASCII characters on the workstation or printer and the internal 
hexadecimal form. The loss of precision can become significant, 
however, when an iterative series of calculations is performed, or 
when the value is compared to an exact value. 


Conversion errors in iterative calculations can accumulate over 
a series of calculations to such an extent that they affect the end 
result. For example, though the arcsine of the sine of 90 degrees 
is 90 degrees, the following program: 


100 SELECT DEGREES /* Set the TRIG mode to DEGREES */ 
200 PRINT ARCSIN(SIN(90) ) 


displays 89.9999994771725 rather than 90. If the result of the 
ARCSIN function were used directly in subsequent calculations, the 
final results of the calculations would be slightly inaccurate; if 
further conversion errors occurred in these calculations, the end 
result could be significantly inaccurate. 


Conversion errors can also significantly influence the result of 
a comparison operation. When two float binary values are compared, 
the comparison is performed on their hexadecimal values. For 
example, the statement IF A = B THEN PRINT C compares the contents 
(in hexadecimal) of A and B; if the two values are not exactly 
equal, the comparison fails. Consider, for example, the following 
short program: 


100 A = 12 
200 B = (12/10) *10 

300 PRINT "A = "; A; "B="; B; "THEY ARE"; 

400 IF A = B THEN PRINT "EQUAL" ELSE PRINT "NOT EQUAL" 


Result: A = 12 B = 12 THEY ARE NOT EQUAL 


This apparently anomalous result illustrates how a loss of 
precision that has no noticeable effect on the result of the 
computation can influence the results of other operations. In this 
case, the division on line 200 produces a result, 1.2, that is 
normal in decimal but is a repeating fraction in hexadecimal 
(because, as noted above, the fraction of 0.2 does not have an exact 
hexadecimal equivalent). When the quotient is multiplied by 10, the 
result in B is not exactly the hexadecimal equivalent of 12, but is 
instead a very close approximation. Since the comparison at line 
400 expects the values of A and B to be exactly equal, the condition 
is not met, and the ELSE statement is executed. However, because 
formatted output statements in BASIC (such as the PRINT at line 300) 
perform an implicit rounding of the result that compensates for the 
one-bit loss of precision, both A and B print as 12. 


For most applications, the loss of precision suffered by float 
binary operations is insignificant and is not a cause of concern to 
the programmer. In those cases where it is a problem, several 
courses of action are available. 


The float decimal representation (refer to Section C.4 and 
Chapter 3) performs floating-point operations with no loss of 
precision. If float decimal is not supported on the user's VS 
system or 1s inappropriate due to other considerations, the ROUND 
function can in some cases reduce the problems associated with the 
float binary representation. However, since the definition of 
rounding (i.e., increase if the digit is greater than or equal to 5) 
is based on the assumption of a decimal number system, ROUND can 
also produce unexpected results when the digit being rounded is very 
close to but slightly less than 5. This is again due to the fact 
that the float binary number is an approximation of the decimal 
number. For example, consider the following program: 


100 C = 30.5 * 11.69 
200 D = ROUND (C,2) 
300 PRINT "C=": C, "D="; D 


Result: C = 356.545 D = 356.54 
The expected result in D is, of course, 356.55. 


For applications in which it is not feasible to use integer or 
float decimal arithmetic, the programmer should consider using a 
PL/I or COBOL subroutine to perform the necessary calculations. 
PL/I and COBOL support packed decimal format, a data format not 
available in BASIC. With packed decimal format, arithmetic 
operations are performed directly in decimal, with no conversion to 
binary. Thus, any loss of precision due to conversion from decimal 
to binary (or to hexadecimal) is avoided. See the VS _ COBOL 
Reference and the VS PL/I Language Reference for a discussion of the 
COBOL and PL/I languages and the data formats available. 


C.4 FLOAT DECIMAL FORMAT 


The range of values for which float decimal calculations are 
precise and consistent is larger than for the integer format, but 
smaller than for the float binary format. On the VS, the range is 
from +1E-65 to +1E63. Standard floating-point operations, including 
arithmetic and relational operators, produce the expected results 
and obey standard mathematical laws, such as those concerning 
associative and commutative operations. For example, float decimal 
equality ("=") tests for exact equality, and it is easy to 
understand when two float decimal values are exactly equal. 


Float decimal calculations, however, are the slowest of all 
numeric operations. In addition, modules compiled with float 
decimal numerics are incompatible with modules compiled with float 
binary numerics; if two modules with different floating-point 
representations share floating-point data, the shared data must be 
converted with the CVDQ or CVQD subroutines described in Part II of 
this manual. The "Inspect and Modify" function of the Symbolic 
Debugger currently does not recognize float decimal data; however, 
the data can be examined in hexadecimal form. Consult the VS 
Principles of Operation for details on the hexadecimal format of 
float decimal data. 


Float decimal format is appropriate for those cases where 
precise results are required, the speed of the calculation is not 
important, and the program does not need debugging. The float 
binary representation is preferred in other cases because it is more 
transportable and faster, and it can represent a larger range of 
values. 


APPENDIX D 
NUMERIC DATA FORMAT COMPATABILITY BETWEEN VS BASIC AND COBOL 


VS BASIC stores integer data as binary integers in four bytes of 
memory (one full word), float binary data as hexadecimal fractions 
in eight bytes, and float decimal data as decimal fractions in eight 
bytes. Other languages, however, may use other formats for storing 
numeric data. In particular, COBOL stores integer data as half-—word 
binary integers, and non-integer numeric data in packed decimal 
format. In packed decimal format, each decimal digit of a number is 
coded into four bits of storage. A hexadecimal digit attached to 
the right (low-order end) of the number indicates the sign. The 
decimal point is not stored; its position is specified only upon 
input or output. 


For most applications, the number representation schemes used by 
other languages are of no concern to the VS BASIC programmer. If a 
BASIC program and a program written in COBOL are to process any of 
the same data, however, this difference cannot be ignored. MThis 
Situation arises if a BASIC program and a COBOL program access the 
same data in either of the following ways: 


l. A BASIC program reads a data file written by a COBOL 
program, or vice versa. 


2. Arguments are passed between a calling program and a 
Subprogram when one program is in BASIC and the other is in 
COBOL. 


Numeric data to be transferred from a BASIC program to a COBOL 
program must first be converted to half-word integer or packed 
decimal format. Similarly, numeric data transferred from a COBOL 
program to a BASIC program must be converted from half-word integer 
or packed decimal to BASIC full-word integer or floating-point 
format before any numeric operations can be performed on them. 


These conversions are most easily accomplished using the BI and 
PD data specification of the FMT statement. For example, to write 
the number 123.45 to a data file to be read later by a COBOL 
program, the following program could be used: 


2600 NUMBER = 123.45 
2700 WRITE #1, USING PACKED DECIMAL, NUMBER 
2800 PACKED DECIMAL: FMT PD(5,2) 


The following line reads a value from a data file that was written 
by a COBOL program: 


3300 READ #2, USING PACKED DECIMAL, VALUE 


Packed decimal numbers are stored as a series of decimal digits with 
no decimal point. When a packed decimal number is read from a file 
and converted to VS BASIC floating-point format, the value is 
converted to the type of floating-point format (float binary or 
float decimal) that is used in the module. The decimal point is 
inserted at the point indicated by the PD specification. As a 
result, the location of the "implied" decimal point must be known 
beforehand, so that the PD’ specification can be written 
appropriately. 


Numeric data passed between BASIC and COBOL calling programs and 
subprograms can be converted between full-word integer or 
floating-point and half-word integer or packed decimal formats using 
the PUT and GET statements in conjunction with a FMT statement with 
a BI or PD specification. Half-word integer and packed decimal 
representations of numbers in VS BASIC must be stored in alpha- 
receivers. For example, a BASIC program can call a COBOL subroutine 
to perform some calculations using the integer variable OPTION% and 
the floating-point variables RATE, TIME, and DISTANCE. Before the 
CALL statement, the data can be converted to the appropriate COBOL 
formats (one half-word integer, and three packed decimal numbers) by 
performing 


5600 PUT OPTION$, USING PD FORM1, OPTION% 

5700 PUT RATE$, USING PD FORM2, RATE 

5800 PUT TIME$, USING PD FORM2, TIME 

5900 PUT DISTANCE$, USING PD FORM2, DISTANCE 

6000 

6100 PD FORM1: FMT BI(2) 

6200 PD FORM2: FMT PD(6,2) 

6300 

6400 CALL ADDR SUB "CRUNCH" (OPTION$, RATE$, TIME$, DISTANCE$) 


Although the arguments passed by the calling program are in a format 
designated by. BASIC as an alphanumeric format, they correspond 
internally to COBOL's half-word integer and packed decimal numeric 
format. After the subprogram ends and control returns to the 
calling program, any changes made to the argument values by the 
COBOL subprograms can be retrieved and used as numeric values by the 
BASIC program with a conversion routine such as the following: 


6500 GET OPTIONS, USING PD FORM1, OPTION% 
6600 GET RATE$, USING PD _FORM2, RATE 

6700 GET TIMES, USING PD FORM2, TIME 

6800 GET DISTANCE$, USING PD FORM2, DISTANCE 


The variables OPTION%, RATE, TIME, and DISTANCE now reflect any 
changes made to these values by the COBOL subprogram. 


Similarly, if a COBOL program calls a BASIC subprogram, the 
numeric arguments from the COBOL program are passed to the BASIC 
subprogram as half-word integers and/or packed decimal numbers. 
Since only alpha-receivers can receive these formats in BASIC, the 
parameters in the SUB statement of the BASIC subroutine must be 
alpha-receivers. Before any numeric operations can be performed, 
the data must be converted (or unpacked) to VS BASIC integer and/or 
floating-point format(s). This is done using the GET statement (as 
above) and FMT statements with the appropriate BI and PD 
specifications. If the subroutine is to pass any numeric data back 
to the calling program, they must first be converted back to 
half-word integer or packed decimal format by PUT statements using 
the appropriate BI and PD specifications in one or more FMT 
statements. 


APPENDIX E 
VS CHARACTER SET 


NOTE: 
bo a/ways 
equals zero”. 


High-Order Digit 


b b b b 
_ 2 6 Z Low-Order Digit 


ryieit 


a 


*Bit combinations 10000000 through 11111111 are field attribute characters. 
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APPENDIX F 


VS FIELD ATTRIBUTE CHARACTERS 


Bright 
Bright 
Bright 
Bright 
Bright 
Bright 


Dim 
Dim 
Dim 
Dim 
Dim 
Dim 


Blink 
Blink 
Blink 
Blink 
Blink 
Blink 


Blank 
Blank 
Blank 
Blank 
Blank 
Blank 


Bright 
Bright 
Bright 
Bright 
Bright 
Bright 


Dim 
Dim 
Dim 
Dim 
Dim 
Dim 


Blink 
Blink 
Blink 
Blink 
Blink 
Blink 


Blank 
Blank 
Blank 
Blank 
Blank 
Blank 


Modify 
Modify 
Modify 
Protect 
Protect 
Protect 


Modify 
Modify 
Modify 
Protect 
Protect 
Protect 


Modify 
Modify 
Modify 
Protect 
Protect 
Protect 


Modify 
Modify 
Modify 
Protect 
Protect 
Protect 


Modify 
Modify 
Modify 
Protect 
Protect 
Protect 


Modify 
Modify 
Modify 
Protect 
Protect 
Protect 


Modify 
Modify 
Modify 
Protect 
Protect 
Protect 


Modify 
Modify 
Modify 
Protect 
Protect 
Protect 


All 
Uppercase 
Numeric 
All 
Uppercase 
Numeric 


All 
Uppercase 
Numeric 
All 
Uppercase 
Numeric 


All 
Uppercase 
Numeric 
All 
Uppercase 
Numeric 


All 
Uppercase 
Numeric 
All 
Uppercase 
Numeric 


All 
Uppercase 
Numeric 
All 
Uppercase 
Numeric 


All 
Uppercase 
Numeric 
All 
Uppercase 
Numeric 


All 
Uppercase 
Numeric 
All 
Uppercase 
Numeric 


All 
Uppercase 
Numeric 
All 
Uppercase 
Numeric 
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No line 
No line 
No line 
No line 
No line 
No line 


No line 
No line 
No line 
No line 
No line 
No line 


No line 
No line 
No line 
No line 
No line 
No line 


No line 
No line 
No line 
No line 
No line 
No line 


Line 
Line 
Line 
Line 
Line 
Line 


Line 
Line 
Line 
Line 
Line 
Line 


Line 
Line 
Line 
Line 
Line 
Line 


Line 
Line 
Line 
Line 
Line 
Line 


APPENDIX G 
ASCII COLLATING SEQUENCE 


Sequence Symbol Meaning 


Ly Space 

2. quotation mark 

36 B') currency symbol 

4. : apostrophe, single quotation mark 
Ds ( left parenthesis 

6. ) right parenthesis 

7. * asterisk 

8. + plus symbol 

3. , comma 

10. - hyphen, minus symbol 
tT. , period, decimal point 
12% / stroke, virgule, slash 
13-22. 0 through 9 

23% ; semicolon 

24. < less than 

25 = equal sign 

26. > greater than 

27-52 A through Z 

53-78 a through z 


APPENDIX H 
VS BASIC ERROR MESSAGES 


The following list contains VS BASIC error messages in 
error-number order. VS BASIC error messages are designed to be 
self-explanatory and  self-—documenting. For more information 
regarding the cause or resolution of an error, see the section 
referenced next to the error message. Note that references to xxx 
and yyy in the list refer to elements of the message that are 
program-specific. 


Error Severity Section 

Number Error Message Return Code Reference 

101 Line number contains invalid 12 2.3 
characters. 

102 Invalid character found. 8 Appendix E 

103 Line number is out of 8 2.3 
sequence. 

104 Literal not completed. 8 3.4 

105 Literal improperly placed 8 2.3, 3.4 
within statement. 

106 Incorrect constant or 8 363 
delimiter. 

107 Constant improperly placed 8 223 Oso 
within statement. 

108 'Non-unique' line number | 
specified. 4 2.3 

109 Invalid identifier name. 8 6.2 

110 Constant too long - 4 343 
Significant digits lost. 

111 Literal too long — Truncated 4 3.4 
to 256 characters. 

112 A character string of length 4 3.4 
zero 1s invalid — Single blank 
substituted. 
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Error 


Number 


113 


114 


115 


116 


117 


118 


119 


120 


121 


122 


124 


201 


202 


203 


204 


205 


Severity 
Error Message Return Code 
Improperly formed picture 8 
constant. 
Numeric constant too large - 4 
Set to largest possible number. 
Numeric constant too small — 4 
Set to zero. 
HEX literal must contain an 8 
even number of characters. 
Invalid boolean function - 8 
must be 0-9 or A-F. 
Invalid HEX literal. 8 
Numeric constant too large 8 
for INTEGER — Treated as 
FLOATING POINT. 
Last line of file contains a 8 
continuation character —- your 
source file may be damaged. 
Invalid exponent found in 8 
floating-point constant. 
Variable name exceeds 64 8 
characters in length - 
Truncated. 
Comment (PL/I style) 8 
unterminated at end of source 
file. 


Expecting end of statement but 8 
xxx was found. 


Expecting line number or label 8 
but xxx was found. 


Expecting statement verb but 8 
xxx was found. 

Expecting yyy but xxx was 8 
found. 

Expecting numeric or alpha 8 


expression but xxx was found. 


Section 
Reference 
3.2 

343 


3.3 


3.4 


3.3 


3.2 


Error Severity Section 


Number Error Message Return Code Reference 
206 Expecting alpha expression but 8 5.4 


xxx was found. 


207 Expecting alpha receiver but 8 5.4 
xxx was found. 


208 Expecting numeric scalar 8 3.37 339 
variable but xxx was found. 


209 Expecting alpha scalar 8 3.4, 3.5 
variable but xxx was found. 


210 Expecting numeric array 8 3.5 
designator but xxx was found. 


211 Expecting alpha array 8 3.5 
designator but xxx was found. 

212 Expecting GOTO or GOSUB but 8 6.1, 6.4 
xxx was found. 

213 Expecting matrix function or 8 9.2 
array variable but xxx was 
found. 

214 Expecting matrix operator but 8 Be 


xxx was found. 


215 Expecting array variable but 8 3.5 
xxx was found. 


216 Expecting relational operator 8 4.2, 5.2 
but xxx was found. 


217 Expecting numeric receiver or 8 Sefer 335 
numeric array designator but 
xxx was found. 


218 Expecting numeric array but 8 3.5 
xxx was found. 

219 Expecting alpha array but xxx 8 3.94 553 
was found. 

220 Expecting alpha array or alpha _ 8 359,543 
array designator but xxx was 
found. 

221 Expecting print delimiter but 8 1.2 


xxx was found. 


Error 
Number 
222 


223 


224 


225 


226 


227 


228 


229 


230 


231 


232 


233 


234 


235 


236 


Error Message 


Expecting 1, 2, 3, or 4 but 
xxx was found. 


Expecting numeric array or 
numeric array designator but 
xxx was found. 


Expecting numeric or alpha 
array designator but xxx was 
found. 


Expecting matrix variable or 


matrix function but xxx was 
found. 


Expecting literal but xxx was 
found. 


Expecting hexadecimal digit 
but xxx was found. 


Expecting numeric constant or 
literal but xxx was found. 


Expecting numeric constant but 


xxx was found. 


Expecting image but xxx was 
found. 


Expecting integer constant but 


xxx was found. 


Expecting array variable or 


alpha scalar but xxx was found. 


Expecting alpha scalar or 


alpha array designator but xxx 


was found. 


Expecting 1 or 2 but xxx was 
found. 


SUB statement may not be 
preceded by any statements 
other than comments. 


xxx has been previously 
defined. 


Severity 


Return Code 


8 


Section 
Reference 


5.6 


Oi WwW 
e e 


BIN entry; 
Part II 


6.5 


4.4 


Error 
Number 
237 
238 
239 
240 


241 


242 


243 


244 


245 


246 


247 


248 
249 


250 


251 


252 


Error Message 


Line number does not precede 
xxx statement. 


Expecting GOTO or GOSUB but 
xxx was found. 


Invalid file number - Valid 
range is 1 to 64. 


Expecting prname literal but 
xxx was found. 


Expecting IOERR or EOD but 
xxx was found. 


Expecting DEGREES, GRADS, 
RADIANS, PAUSE, CRT, WS, 
POOL, PRINTER, or file 
expression but xxx was found. 


The SELECT statement must 
precede any disk Input/Output 
statements. 


Either equal sign is missing 
in a LET statement or this 
statement starts with an 
unrecognizable word. 


Multiply defined parameter in 
OPEN statement. 


Expecting DATA but xxx was 
found. 


Expecting EOD but xxx was 
found. 


Function previously defined. 
Invalid number of arguments. 


Expecting integer 0-255 but 
xxx was found. 


Expecting a function but 
xxx was found. 


Expecting OPEN mode indication 
(INPUT, OUTPUT, IO, SHARED, or 


EXTEND) but xxx was found. 
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Severity 


Return Code 


8 


Section 
Reference 
2.3 

6.1, 6.4 


8.3 


8.3 


8.3 


Error 
Number 
253 


254 


255 


256 


257 


258 


259 


260 


261 


262 


263 


264 


265 


266 


267 


268 


269 


Error Message 


Invalid argument type in SUB 
statement. 


Expecting format statement 
specification but xxx was 
found. 


Expecting file expression but 
xxx was found. 


Expecting error specification 
but xxx was found. 


Expecting file number or 
BLOCKS but xxx was found. 


Expecting comma or equal sign 
but xxx was found. 


This statement too long. 


Expecting keyword option but 
xxx was found. 


Missing comma before xxx. 
Expecting equal sign or 
parenthesis after yyy but xxx 


was found. 


Expecting CONSEC or INDEXED 
but xxx was found. 


Invalid use of xxx in ACCEPT 
statement. 


Incorrect number of 
subscripts. 


Length must be in range l 
to 256. 


XXX is not a valid name. 


Invalid use of xxx in DISPLAY 
statement. 


Nested IF statements are not 
allowed. 


Severity 


Return Code 


8 


Section 
Reference 


6.5 


7.4 


Chapter 8 


8.3 


8.3 


4.2, 5.2 


Error Severity Section 


Number Error Message Return Code Reference 

270 xxx not yet implemented in 8 169% 26 
ACCEPT or DISPLAY. 

271 xxx already specified in 8 7.5 
ACCEPT. 

272 File was not previously 8 8.3 
specified in a SELECT 
statement. 

273 Invalid device type for this 8 8.3 
function. 

274 Invalid file attributes for 8 8.3 
this function. 

275 File # xxx. is already defined. 8 8.3 

276 Invalid alternate key number — 8 8.3 
Must be in range 1 to 16. 

277 Invalid alternate key for this 8 8.3 
file. 

278 File does not have alternate 8 8.3 
indices. 

279 Alternate index number already 8 8.3 
used. 

280 Expecting TO, SUB, or SUB' but 8 6.5 


xxx was found. 


281 Pause interval must be in 8 8.3 
range 1 to 255. 


282 Expecting TO or SUB after GO 8 6.3, 6.4 
but xxx was found. 


283 A field attribute character 8 7.5 
(FAC) may not immediately 
precede a literal. 


284 Expecting comma or BEG but xxx 8 8.3 
was found. 

285 Label xxx already exists. 8 23 

286 Label yyy was previously 8 2.3 


defined aS a xxx. 


Error 
Number 
287 
288 


289 


290 


291 


292 


293 


294 


295 


296 


297 


298 


401 


402 


403 


404 


Error Message 


Variable yyy was previously 
defined as a xxx. 


Function yyy was previously 
defined as a xxx. 


Label xxx may not end with a 
$ or % character. 


A string value may not be 
assigned to numeric receiver 
xxx. 


A numeric value may not be 
assigned to alpha receiver 
XXX. 


TRACE statement no longer 
supported — Use the symbolic 
debugger. 


Null statement invalid after 
THEN or ELSE. 


YYY may not be declared as 
XxX variable. 


Array dimension must be in 


the range 1 to 32767 — Default 


value of 10 used. 


Format specifications must be 


greater than zero. 


Expecting PIC but xxx was 
found. 


The FILESEQ option is valid 
only for TAPE files. 


Invalid operand in PRINT 
statement. 


Compiler error. 


Compiler error due to prior 
errors. 


xxx invalid in USING list. 
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Severity 


Return Code 


8 


12 


12 


Section 
Reference 


3.3, 3.4 


4.4 


3.2, 3.4 


Appendix A 


4.2, 5.2 


3.2 


3.5 


7.4 


7.5 


8.3.2 


7.5 


1.4 


1.4 


7.4 


Error 
Number 


405 


406 


407 


408 


409 


410 


411 


412 


413 


414 


415 


416 


417 


418 


419 


420 


Severity 


Error Message Return Code 
An invalid subroutine name or 4 

PRNAME has been corrected or 

replaced. 

Invalid OPEN option for this 8 


file access method. 


Line number xxx missing before 6 
this line. 


Constant invalid - Out of 8 
range. 
SUB argument may not be 6 


declared in COMMON. 


Invalid picture used in PACK, 6 
UNPACK, or CONVERT statement. 


Invalid line length in SELECT 4 
statement. 


FORM statement contains an 6 
invalid number in a FL or BI 
data specification. 


Target line number is invalid 8 
for this type of statement. 


This file was not previously 4 
SELECTed. 
File already specified in 4 


SELECT, POOL statement. 


Code efficiency reduced due 4 
to complexity of expression. 


Invalid constant used as a 8 
subscript. 

Alternate key number must be 8 
in range 1 to 16. 

Invalid alternate key 8 
specification. 

File number must be within 8 


range 1 to 64. 
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Section 
Reference 


6.5, 8.3 


Error 
Number 
421 
422 
423 


424 


425 


426 


427 


428 


429 


430 


431 


432 


433 


434 


435 
436 


437 


Error Message 


This file has already been 
SELECTed. 


Invalid record size specified. 


The last character of the key 
is beyond the end of the 
record. 


Target line number for EOD or 
DATA exit is invalid. 


Integer matrix may not be the 
result operand of matrix 


inversion. 


Prname truncated to eight 
characters. 


Prname contains invalid 
character or starts with a 
digit. 


Generated STATIC area too 
large. 


Program too large to compile: 
XXX. 


The selected file is not an 
indexed file — Buffer pooling 
may not be used. 


Compiler error: xxx. 


User function or routine is 
not defined. 


Generated COMMON area too 
large. 


Combined COMMON and STATIC 
areas too large. 


Array xxx too large. 
Block size invalid. 


Invalid tape density. 
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Severity 


Return Code 


8 


12 


16 


12 


12 


12 


12 


Section 
Reference 
8.3 

8.3 


8.3 


8.3 


8.3 


1.4 


4.4, 6.4 


8.3 


8.3 


Error Severity Section 


Number Error Message Return Code Reference 
438 Line numbers greater than 6 1.4, 2.3 


65535 are incompatible with 
SYMBOLIC DEBUG ~— Use the 
EDITOR to renumber your 
program in smaller increments 
if you wish to use the 


symbolic debugger. 


439 Statement will cause run-time 8 1.4 
Stack overflow. 


440 Statement too long. 12 2ce% 223 

441 Label xxx missing. 6 263, 6.2 

442 Primary key length may not 8 8.3 
exceed 255 characters. 

443 Alternate key extends beyond 8 8.3 
the end of the record. 

444 Alternate key length may not 8 8.3 
exceed 255 characters. 

445 Alternate key number has 8 8.3 
already been specified for 
this file. 

446 The sum of the lengths of 8 8.3 


the primary key and any 
alternate key may not exceed 
255 characters. 


447 xxx, yyy is referred to only 4 N/A 
once in this program. Check 
for possible spelling errors. 


448 Subscripts out of range in 6 Dao 
STR function. 


449 KEY clause precedes KEYS 4 Tad 


clause in ACCEPT statement: 
KEYS clause will be ignored. 
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APPENDIX I 
CVBASIC USER AID (CONVERSION from BASIC 2.3 to 3.2) 


I.1 INTRODUCTION 


CVBASIC is provided as an aid to the BASIC programmer for 
converting from Version 2.3 of VS BASIC to Version 3.2 of VS BASIC. 
Since Version 3.2 programs are compatible with Version 3.4 programs, 
no further conversion is required. CVBASIC converts source code, 
residing in single files or libraries, from Version 2.3 syntax to 
3.2 syntax. Input to the utility must be syntactically correct 
Version 2.3 source code. Once the conversion program is complete, 
the output source file/library is created and an update listing is 
produced that indicates the success or failure of the conversion. 
This listing can be displayed at the workstation, or it can be 
printed. If the conversion was not successful, an error message 
indicates the reason for the error and suggests corrective action. 
The output source code can then be compiled by a Version 3.2 or 
above BASIC compiler. 


BASIC Versions 3.2 and above support variable names up to 64 
characters in length. CVBASIC accommodates this by inserting 
necessary spaces between the elements in the language, such as 
variables, reserved words and constants. 


A summary oof additional syntax changes that | CVBASIC 
automatically converts includes: 


1. Insert spaces around all VS BASIC reserved words: 


2. Convert SELECT D to SELECT DEGREES, 
SELECT R to SELECT RADIANS, 
SELECT G to SELECT GRADS, 
SELECT P to SELECT PAUSE 


3. Convert #PI to PI; 
4. Convert CONVERT X to Y, (###) to 
CONVERT X to Y, PIC (###); 
5. Convert FMT PD (X.Y) to FMT PD (X,Y); 
6. Convert TRANS (A$,B$)R to TRANS(A$,B$) REPLACING; 
7. Convert PACK (###) TO PACK PIC (###); 
8. Convert UNPACK (4#+##) to UNPACK PIC (##4+); 
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I.2 USING CVBASIC 


The screens in the figures below indicate the information needed 
to define the input and output of this program. Once CVBASIC is run 
successfully, the output source programs must then be compiled under 
Version 3.2 or above of the compiler. In addition, a listing of the 
files that were converted and any errors that occurred is produced. 
This error listing explains the conditions that prevented the 
conversion and provides possible error correction solutions. If the 
library option is chosen and any of the files in the library are not 
valid source files, those files are automatically skipped. The 
names of the skipped files are written to the error listing. 


*** MESSAGE INPT BY CVBSIC 


INFORMATION REQUIRED BY PROGRAM CVBASIC 
TO DEFINE INPUT 


CVBASIC - VS BASIC source conversion utility 


This utility converts VS BASIC 2.3 source files to VS BASIC 3.2 source files. 


Please specify the file or library to be converted: 
FILE SUR RESe Ae LIBRARY = MLHLIB** VOLUME = ZENITH 


and select: 
(2) Convert a single file 
(3) Convert an entire library (leave the FILE name blank) 


or select: 
(13) Instructions 
(16) Exit from CVBASIC 


*** MESSAGE FILE BY CVBSIC 


INFORMATION REQUIRED BY PROGRAM CVBASIC 
TO DEFINE OUTPUT 


CVBASIC - Source file conversion parameters 


Please ENTER the output file for the converted source 
or 
Press PF2 if you wish to replace input file MGLLOGON 


FILE So NR SANKSS LIBRARY = MLHOBJ** VOLUME = ZENITH 


When the conversion has been completed, the results 
may be printed or displayed at the workstation. 


Or select: 
(13) Instructions 
(16) Return to main menu 


Information required to define input and output for CVBASIC 


CVBASIC can be run from a procedure or from the Command 
Processor. The parameters needed for writing procedures are listed 
in the table below. Conversions can be run as batch tasks only if 


they are fully parameterized (see the VS _ Procedure Language 
Reference). 
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INPUT FILE Blank 

(main menu) LIBRARY : User's INLIB 
VOLUME 6 User's INVOL 
PF Keys* 1l=Convert a file 


2=Convert a library 
13=Instructions 
16=Exit program 


OUTPUT FILE 


(file) LIBRARY 8 User's OUTLIB 
VOLUME 6 User's OUTVOL 
PF Keys* b=Cont inue 


2=Replace input 
file 
13=Instructions 
16=Return to main 
menu 


OUTPUT LIBRARY User's OUTLIB 


(library) VOLUME 6 User's OUTVOL 
NOTIFY 3 YES/NO NO 
PF Keys* 13=Instructions 


16=Return to main 
menu 


FILE 8 CVBA + unique 


PRINT 
(output 4~—digit 
listing) number 
LIBRARY 8 User's 
SPOOLIB 
VOLUME 6 User's 


SPOOLVOL 


ERROR PF Keys* 1=Return to main 
(if no menu 

errors 11=Display results 
occurred) 15=Print results 


16=Exit CVBASIC 


1=Return to main 
menu 
11=Display errors 
13=Instructions 
15=Print errors 
16=Exit CVBASIC 


ERROR 
(if errors 
occurred) 


RENUMBER PF Keys* 1=Skip this file | 
(edit the 5=Renumber this 
file and file 


renumber it) 13=Instructions 
16=Return to main 


menu 


| * The keyword is not required. 
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If CVBASIC is run interactively from a workstation, the name of 
the file undergoing conversion processing is displayed along with 
file size information. If the NOTIFY option is selected or only one 
file is being converted, the user is notified of any errors that 
occurred after the conversion is complete. If the error can be 
corrected by renumbering the file, the user has the option of 
calling the EDITOR to renumber; the conversion is then automatically 
attempted again. If errors occur during processing, the error 
screen is displayed for the user to display or print the listing, 
return to the CVBASIC main menu, or leave the program. 


I.3 PROGRAM EXAMPLE 


This 1s a compilable program under Release 2.3 of VS BASIC that 
must be converted before it can be run under Release 3.2 or above of 
VS BASIC: 


100 SELECT D,P9 
200 INPUTX 

300 Y=SIN(X) 

400 CONVERT Y TO Z$, (##.##) 
500 PRINTZ$ 

600 GOTO200 


When this program is used as the input program file for CVBASIC, 
the resulting file is: 


100 SELECT DEGREES, PAUSE 9 

200 INPUT X 

300 Y=SIN(X) 

400 CONVERT Y TO Z$, PIC (##.#+#) 
500 PRINT Z$ 

600 GO TO 200 


Note that spaces were provided, the abbreviated names were 
expanded to their more self-—documenting form, and the PIC clause was 
added. These changes make long variable names possible and 
generally increase the clarity, readability and self-documenting 
nature of VS BASIC. 


SUMMARY OF CHANGES 
FOR THE 3rd EDITION OF VS BASIC LANGUAGE REFERENCE 


TOPIC DESCRIPTION Loe 


PRINT FILES CLOSE PRINTER 140 
SELECT PRINTER 140, 256 


Miscellaneous Technical and 220, 253 
Editorial 256, 266 
277 
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SUMMARY OF CHANGES 


FOR THE 2nd EDITION OF THE VS BASIC LANGUAGE REFERENCE MANUAL 


Release 3.2 


Syntax Changes 


Prerelease 3.2 


One or two character 
variable names 

#PI intrinsic function 
SELECT D 

SELECT G 

SELECT R 


CONVERT X TO Y$, (###) 
FMT PD (6.4) 
Nonnumeric file, li- 
brary, and volume name 
only 

PACK (+###) 


SELECT P 
TRAN [R] 
UNPACK (###) 


General Miscellaneous editorial changes 
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Release 3.2 


Required spacing within 
a statement 
Long variable names 


PI intrinsic function 
SELECT DEGREES 

SELECT GRADS 

SELECT RADIANS 
Statement labels 
FILESEQ for tape files 
CLOSE WS 

CLOSE CRT 

CONVERT X TO Y$,PIC(+###) 
FMT PD (6.4) 

Numeric file, library, 
and volume name 


PACK PIC (43) 
SELECT WS 
SELECT PAUSE 
TRAN [REPLACING] 
UNPACK PIC (#+##) 


35,214,235 
36,256 
36,256 
36,256 

62,63 

100, 220-223 
140 

140 

142 

152-154 


220 
225,226 
256 
256 

273 

274 


Term 


alphanumeric 


alphanumeric 
array string 


alphanumeric 
expression 


alphanumeric 
variable 


argument 


array 


array 


designator 


array element 


associative 


bit 


GLOSSARY 


Definition 


A data type that represents uppercase and lowercase 
letters (A through Z, a through z), numbers (0 
through 9), and special characters (such as %, $, 
?). Each alphanumeric character requires one byte 
of storage. Languages such as FORTRAN and PL/I 
refer to alphanumeric data as character data. 


An alphanumeric array that is treated as a single 
data item. 


One or more literals, alphanumeric’ variables, 
alphanumeric array strings, or alphanumeric 
functions optionally joined as operands of 


alphanumeric operators. 


A variable that accepts alphanumeric data items. 


A data item used as input to a function or 


subroutine. 


A one- or two-dimensional set of data items with the 
same data type that can be referenced collectively 
by a common name (see array designator). 


An array name followed by a set of empty parentheses 
(e.g., A()). An array designator references’ the 
entire array as a unit. 


A single array data item. An individual array 
element can be referenced by a subscripted form of 
the name. 


A mathematical property of an operation whereby the 
order in which a _ series of such operations is 
performed does not affect the result. For example, 
the expression A+B+C is associative because 
(A+B) +C=A+(B+C). 


(Binary digiT). The smallest unit of data storage. 
A bit can have the value zero or one. 


GLOSSARY-1 


buffer 


byte 


character 
string 


comment 


commutative 


concatenation 


consecutive 
file 


constant 
control- 
specification 


data- 
specification 


data type 


determinant— 
variable 


dimension 


executable 
program 


Definition 


A temporary storage place for input or output data 
that compensates for the different rates of data flow 
when transferring data from one device to another. 


Eight sequential bits that form a unit in memory. 


An alphanumeric data item enclosed in matching single 
or double quotes. 


Any user-written message. The BASIC compiler ignores 
comments, but puts them on listings as written. 


A mathematical property of an operation whereby the 
order in which its operands are placed does not 
affect the result. For example, the expression A+B 
is commutative because A+B=B+A. 


An alphanumeric operation that sequentially combines 


two or more alphanumeric strings into aé_ single 
string. 
A file whose records can only be _ = accessed 


sequentially or by relative record number. 


A value or literal data item that does not change in 
value. 


A clause in a format statement that specifies the 
relative location of an output data item. 


A clause ina format statement that determines the 
data type and format of input or output values. 


The property of a data item that determines’ the 
internal representation of the item and in what 
types of expressions the item can be used. BASIC 
supports alphanumeric, float binary, float decimal, 
and integer data types. 


A variable supplied by the programmer to receive the 
value of the matrix determinant that is calculated as 
part of an inversion operation. 


The number of subscripts that an array can contain 
(i.e., whether the array is a vector or table). 
Also, the maximum number of elements in a given 
array dimension. A BASIC array can contain from 1 
to 32,767 elements in a particular dimension; the 
default number of elements is 10. 


It consists of 
optionally, any 


A program that the processor can run. 
one compiled main program and, 
number of compiled subprograms. 
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Term 
executable 
statement 
expression 


EXTEND mode 


file- 
expression 


filename 


float binary 


float decimal 


format 


format 
specification 


function 


Image 


indexed file 


INPUT mode 


integer 


Definition 


A statement that calculates, tests, or changes the 
flow of control. 


One or more constants, variables, or functions, 
optionally connected by operators. 


An open mode in which a program can write to a 
consecutive file, but cannot read the file. 


A pound sign (#), followed by a numeric expression, 
that references a file in all file I/O operations. 


An alphanumeric value of up to eight characters that 
identifies a physical file. The value must begin 
with an alphabetic character, integer, @, $, or #, 
and cannot contain embedded spaces. 


A data type that represents fractional and very large 
and very small numbers in scientific notation. Float 
binary values can be values ranging from 
+5.4 x 10°’° to +7.2 x 10’°. The range of float 
binary values is larger than that of the float 
decimal data type (see definition below), but float 
binary operations can lose precision in some cases. 


A data type that represents fractional and very large 
and very small numbers in scientific notation. Float 
decimal values represent a slightly smaller range of 
values (+1 x 10°°° to + 1 x 10°*) than the float 
binary data type (see definition above), but float 
decimal operations are more precise. 


A statement that describes the arrangement of data. 


A clause in a format statement that creates a logical 
"picture" of the data being output. 


A subroutine that returns a single value. 


A logical "picture" of the format desired for an 
output operation. 


A file whose records can be accessed either by key 
value or sequentially. 


An open mode in which a program can read, but not 
modify, a file. 


A data type that represents "whole" numbers ranging 
from —2,147,483,648 to 2,147,483,647. 


GLOSSARY-3 


Term 


intrinsic 
function 


IO mode 


keyword 


label 


library 


literal 
logical 
expression 


null label 


numeric 
constant 


numeric 
expression 


numeric scalar 
variable 


numeric 
variable 


OUTPUT mode 


print file 


Definition 


A function that is defined by the compiler. 


An open mode in which a program can both read and 
modify a file. 


A word defined for reserved use within a computer 
language. 


An identifier that is assigned to a statement for 
later reference. 


Identifies a physical file as existing in a 
particular group of files. The library name cannot 
exceed eight alphanumeric characters. The value must 
begin with either an alphabetic character, @, $, or 
#, and cannot contain embedded spaces. 


An alphanumeric data item whose value is fixed during 
program execution. 


An alphanumeric expression containing any of several 
logical operators (ADDC, ADD, AND, OR, XOR, BOOLh). 


A place-holder in GOTO or GOSUB statements that 
effects no transfer of control if the value of the 
tested expression equals the value of that place in 
the list of transfer points. 


A numeric data item whose value is fixed during 
program execution. 


One of a series of constants, variables, or functions 
connected by arithmetic operators. 


A variable that contains a single numeric value. 


A variable used to reference numeric data in memory. 


An open mode in which a program can create and write 
records to a (possibly newly created) file. A 
program cannot read records from a file in OUTPUT 
mode. 


A consecutive file intended for use by the printer. 
A print file contains printer control bytes that 
control such printer operations as line feeds, page 
breaks, and the alarm. 
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Term 


prname 


pseudovariable 


random 
access 


receiver 


relational 
expression 


scalar 


scalar 
variable 


sequential 
access 


SHARED mode 


statement 
label 


string 
dimension 


subroutine 
subscript 


substring 


variable 


volume 


Definition 


A literal string used as the parameter reference name 
for a given file. 


A function that acts as a receiver. 


A method of accessing records in a file in any order. 
An indexed file can be accessed randomly by a key 
value; a consecutive file can be accessed randomly 
by relative record number. 


A variable or function to which data can be assigned. 


An alphanumeric or numeric expression containing a 
relational (<, >, <=, >=, =, <>) operator. 


A value represented by a single data item. 


A variable containing a single value. 


A method of accessing a file's records in successive 
order. 


An open mode in which a program can both read and 
modify records in an indexed or consecutive log file. 


A character string used as a label reference for a 
statement. A label must immediately precede _ the 
statement. 


The maximum length of an alphanumeric data item 
(character string). The length can range from 1 to 
256, inclusive, and defaults to 16. 


A subprogram that can be called to perform a service 
for the main program. 


An integer expression that follows an array name to 
identify a particular array element. 


A portion of an alphanumeric variable that the STR 
function creates. STR forms the substring by 
abstracting a specified number of characters from a 
specified starting value in the original string 
variable. 


A named data item whose value can change. 


Identifies a physical file as residing on a specific 
disk or tape. The volume name can contain no more 
than six alphanumeric characters. The value must 
begin with either an alphabetic character, integer, 
@, $, or #, and cannot contain embedded spaces. 
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Term 


word 


WP file 


Definition 


A group of bytes (four on the VS) that is treated, 
storable, and addressed as a unit. 


A consecutive disk file that is organized for access 
by VS Word Processing or the Document Access 
Subroutines. WP files include VS word processing 
documents and OIS files. BASIC programs cannot 
access OIS files, and can only access VS_ word 
processing documents through the Document Access 
Subroutines. 
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INDEX 


A 


ABS (absolute value). function, 
4-7, ITI-3, II-97 
ACCEPT statement, 7-2, 7-8 to 
7-15, II-4 to II-9 
ALT clause, 7-14 
AT clause, 7-10 
CH clause, 7-11 
data entry, 7-11 
data validation, 7-12 
FAC clause, 7-10 to 7-11 
fields, 7-9 to 7-10 
KEY clause, 7-13 
KEYS clause, 7-13 
NO ALT clause, 7-14 
ON Key clause, 7-14 
PF keys, 7-13 
PIC clause, 7-11 
positioning data, 7-10 
RANGE clause, 7-12 
screen formatting, 7-9 
ADD[C], 5-11, 5-12, II-10 to 
II-11 
Addition, 4-2 
priority of, 4-2 
ADDR-type subroutines, 6-9, 6-12 
ALL, 5-6, II-12 
Alpha array strings, 5-4, 
Glossary-1 
Alpha expressions, 5-5 
Alpha receivers, 5-5 
Alphanumeric, 3-7 to 3-10, 5-1 
array, 3-9 
constants (see literal 
strings), 3-7 to 3-8 
data, 3-7 
definition of., Glossary-1 
expressions, 5-5, Glossary-1 
functions, 5-6 
literal strings, 3-7 to 3-8 
operations, 5-16 to 5-17 
operators (see also 
alphanumeric data, logical 
operators with), 5-1 to 5-4 
‘receivers, 5-5 
scalar, 3-9 
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terms, 5-14 to 5-15 
variables, 3-9 to 3-10, 


Glossary-1 
Alphanumeric data formats, 5-13 
to 5-17 
alphanumeric length, 5-13 to 
5-14 


defined length, 5-14 
AND logical operator, 5-11, 5-12, 
II-13 
ARCCOS (arccosine) function, 4-6, 
II-14, II-96 
ARCSIN (arcsine) function, 4-6, 
II-15, II-96 
ARCTAN (arctangent) function, 
4-6, II-16, II-96 
Argument, definition of, 
Glossary-1 
Argument in user-defined 
functions, 4-11 
Array, 3-1, 3-11 to 3-15 
alphanumeric, 3-9 
array strings, 5-13 
comparison between one- and 
two-dimensional, 3-12, 3-13 
default dimensions, 3-14 
defining, 3-1, 3-9, 3-11 
definition of, Glossary-1 
dimensioning, 3-14 to 3-15, 9-3 
to 9-4 
elements of, 3-6, 3-11, 
Glossary-1 . 
expressions in, 3-11 
input values for, through INPUT 
statement, 3-11 
length of elements, 3-14 
naming, 3-11 
numeric, 4-14 to 4-15 
one-dimensional, 3-12 
subscripts, 3-13 
two-dimensional, 3-12 to 3-13 
Array assignment statement, 9-2 
operations with, 9-2 
redimensioning arrays with, 
9-2, 9-3 
Array designator, definition of, 
3-11, Glossary-1 


INDEX (continued) 


Array variables, 3-11 to 3-12 

Assignment statement, 9-2, II-73 

Associative, definition of, 
Glossary-1 

ATN (arctangent) function, 4-6, 
II-17, II-96 


B 


BASIC character set, E-1 
BASIC compiler, 1-9 to 1-11, B-1l 
to B-3 

DFLOAT, 1-9, B-3 

ERRLIST, B-3 

FLAG, B-3 

LINES, B-3 

LOAD, 1-9, B-2 

options, 1-9, B-1l to B-3 

PMAP, B-1 

SOURCE, 1-9, B-1l 

STOP, B-3 

SUBCHK, B-2 

SYMB, 1-9, B-2 

XREF, B-2 
BASIC statements, II-1 to II-167 
BIN function, 5-6, II-18 
Bit, definition of, Glossary-1 
Blanks, 2-3 to 2-4 

in Image (%) statement, II-64 
BOOLh logical operator, 5-11, 

5-12, II-19 

Branching, 6-2 

program, 6-2 

subroutine, 6-2 
Buffer, definition of, Glossary-2 
Byte, definition of, Glossary-2 
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CALL statement, 6-1, 6-2, 6-8 to 
6-17, II-21 to II-23 

Character set, BASIC, E-1 

ASCII collating sequence of, 

G-1 

Character string, 3-10, 
Glossary-2 

CLOSE statement, 8-7 to 8-9, 
II-24 to II-25 

Closing files (see CLOSE 
statement), 8-7 to 8-9, 
II-24 to II-25 
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COM statement, 3-14 to 3-15, 
6-13, II-26 
Comma, II-48 
as an insertion character in 
FMT statement, II-48 
use in INPUT statement, II-67 
use in PRINT statement, II-124 
Comment, 2-5, Glossary-2 
in program, 2-5, 2-6 
in REM statement, 2-5 
in * statement, 2-5 
Commutative, definition of, 
Glossary-2 
Compiler, 1-5, B-1 to B-3 
BASIC, 1-5, 1-9 to 1-11, B-1 to 
B-3 
EDITOR, 1-6 to 1-9 
Compiler options, 1-9, B-1 to B-3 
Computed GOSUB statement, II-55 
Concatenation (&), 5-2 to 5-3, 
Glossary-2 
Consecutive files, 8-1, 8-2, 
Glossary-2 
Constants, 3-1, 3-5, 3-7 to 3-8 
definition of, 3-1, Glossary-2 
Control specification, in FMT 
statement (see also FOS, 
SKIP, and X), II-47, 
Glossary-2 
Control statements, 6-1 to 6-18 
branching, 6-2 
conditional, 6-2 
exit conditions, 6-2 
halting execution, 6-1 
looping, 6-2 
subroutine, 6-2 
unconditional, 6-2 
Control variable, in FOR 
statement, II-50 
CONVERT statement, 9-1, II-27 to 
II-~28 
COPY statement, II-29 
COS (cosine) function, 4-6, 
II-30, II-96 
Current length, 3-10 
Current value, 3-10 
Cursor, 1-3 
CVDQ subroutine, 3-3, II-31 
CVQD subroutine, 3-3, II-32 
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Data (see alphanumeric and 
numeric), 3-1 
alphanumeric, 3-7 to 3-10 
in FMT statement, II-47 to 


II-49 

in Image (%) statement, II-64 
to II-65 

in INPUT statement, II-67 to 
II-69 


in scalar assignment statement, 
(LET), II-73 to II-74 
literals (alphanumeric 
constants), 3-7 to 3-8 
numeric, 3-2 to 3-7 
Data Management System (DMS), 
1-4, 8-1, 8-4, 8-7 
Data specification, definition 
of, Glossary-2 
DATA statement, II-33 
relationship to READ statement, 
II~-33 
relationship to RESTORE 
statement, II-33 
Data type, definition of, 
Glossary-2 
DATE function, 5-6, II-34 
Decimal point (.) 
in PRINT statement, II-125 
insertion character in FMT 
statement, II-48 
DEF statement, 4-11, II-35 to 
II-36 
DEF FN' statement, 6-5, 6-7, 
II-37 
DEF function definition, 4-11, 
II-35 to II-36 
Defining 
COM statement, 3-14 to 3-15, 
6-10, 6-13, II-26 
DIM statement, 3-14 to 3-15, 
II-41 
DELETE statement, 8-12, II-40 
restriction with consecutive 
files, 8-12, II-40 
Delimiters (see PRINT, INPUT), 
II-115 
Determinant—variable, definition 
of, Glossary-2 
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Dimension, definition of, 
Glossary-2 
DIM function, 4-7, 4-8, II-42 
DIM statement, 3-14 to 3-15, 
II-41 
defining alphanumeric data 
with, II-41 
defining arrays with, 3-14 to 
3-15, II-41 
DISPLAY statement, 7-1, 7-15, 
II-43 
DPACK keyword in OPEN statement, 
II-108 
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EDITOR, 1-6 to 1-9 
EJECT compiler directive, 2-6, 
II-44 
ELSE keyword in IF statement, 
6-1, 6-2, II-62 to II-63 
END statement, 6-1, II-45 
Error messages, H-1 to H-11l 
EXP (natural exponential) 
function, 4-7, II-46, II-97 
Expression, definition of, 3-2, 
Glossary-3 
evaluation of, 4-2 to 4-3 
relational operators in, 4-4 
EXTEND mode, definition of, 8-8, 
Glossary-3 
External subroutines, 6-8 to 6-18 
argument types, 6-15 to 6-17 
arguments, 6-10 to 6-12 
common variables, 6-13 to 6-14 
compiling, 6-9 to 6-10 
form, 6-9 
initialization, 6-14 to 6-15 
linking, 6-9 to 6-10 
operation of, 6-8 
passing values, 6-10 to 6-14 
running, 6-10 
use of, 6-17 to 6-18 


FE 


FAC (Field Attribute Character), 
7-4 to 7-5 

Field format, II-116 to II-117 

Field types, II-117 to II-119 
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File expression, definition of, 
8-5, Glossary-3 
File hierarchy, 1-4 to 1-5 
file, 1-4, Glossary-3 
library, 1-5, Glossary-4 
volume, 1-4, Glossary-5 
File I/O buffering and record 
area, 8-10 to 8-11 
File I/O modes, 8-9 to 8-10 
File input/output statements, 
8-12 to 8-14 
data representation, 8-12 
errors, 8-17 to 8-18 
examples, 8-18 to 8-22 
CLOSE statement, 8-7 to 8-9, 
II-24 to II-25 
DELETE statement, 8-12, II-40 
GET statement, 8-12, II-53 
OPEN statement, 8-7 to 8-9, 
II-107 to II-110 
PUT statement, 8-13 
READ statement, 8-12, II-130 to 
II-131 
REWRITE statement, 8-13, 
II-136, II-137 
WRITE statement, 8-12, II-165 
to II-166 
File types, 8-1 to 8-3 
Filename, definition of, 1-5 
FILESEQ keyword in OPEN 
statement, II-108 
Files, 8-1 
Float binary, 1-2, 3-2 to 3-5, 
4-7, II-31, II-32, C-1 to 
C—4, Glossary-3 
Float decimal, 1-2, 3-2 to 3-5, 
4-7, II-31, II-32, C-1 to 
C-4, Glossary-3 
Floating-point and integer 
calculation, 1-2, 3-3, 3-4, 
C-1 to C-4 
Floating-point calculation, 1-2, 
3-2 to 3-4, II-31, II-32, 
C-1 to C-4 
Floating-point constant, 
(E-format), definition of, 


3-4 to 3-5 

Floating-point data, 3-2 to 3-7, 
4-12 

FMI statement, 7-5, 7-6, II-47 to 
II-49 . 


use of, 7-5, II-47 to II-49 
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used with files, II-47 
used with PRINTUSING, II-47 
FOR statement, 6-1, 6-2, II-50 
FORM statement, II-51 
Format control specifications in 
FMT Statement (see also X, 
POS, SKIP), 7-5, 7-6, II-47 
to II-49, Glossary-3 
FS function, 8-15, II-52 
Functions 
ABS, 4-7, II-3, II-97 
ALL, 5-6, II-12 
ARCCOS, 4-6, II-14, II-96 
ARCSIN, 4-6, II-15, II-96 
ARCTAN, 4-6, II-16, II-96 
ATN, 4-6, II-17, II-96 
BIN, 5-6, II-18 
COS, 4-6, II-30, II-96 
DATE, 5-6, II-34 
definition of, Glossary-3 
DIM, 4-7, 4-8, II-42 
EXP, 4-7, II-46, II-97 
FS, 5-6, 8-15, II-52 
HEX, II-57 
INT, 4-7, II-70, II-97 


KEY, 5-6, 8-15 to 8-16, II-71 
LEN, 4-7, 5-7, 11-72 

LGT, 4-7, ITI-75, II-97 

LOG, 4-7, II-76, II-97 


MASK, 5-6, 8-16, II-77 

mathematical, II-96 to II-100 

MAX (maximum value), 4-7, 
II-98, II-101 

MIN (minimum value), 4-7, 
II-98, II-102 

MOD, 4-7, I1I-99, II-103 

NUM, 4-8, 5-7, II-105 

other numerical, 4-6 to 4-10, 
II-97 

PI, 4-5, II-100, II-122 

POS, 4-8, 5-7, II-123 

RND, 4-8, 4-9 to 4-10, II-138 

ROUND, 4-8, 4-10, II-140 

SGN, 4-8, II-97, II-148 

SIN, 4-6, II-96, II-149 

SIZE, 4-8, 8-16, II-150 

SOR, 4-8, II-97, II-152 

STR, 5-6 to 5-7, II-154 

TAN, 4-6, II-96, II-158 

TIME, 5-6, II-159 

trigonometric, 4-6, II-96 

VAL, 4-8, 5-7, 5-10, II-164 
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GET statement, 8-12, II-53 

GOSUB statement, 6-1, 6-2, 6-4 to 
6-5, II-54 

GOSUB' statement, 6-1, 6-2, 6-5 
to 6-7, EI-55 

GOTO statement, 2-1, 6-1, 6-2, 
II-56 


|: ee a Re ee Se ered ee 


Hexadecimal/decimal conversion 
errors, 1-2, 3-3, C-l to 
c-4 

Hexadecimal function (HEX), II-57 

HEXPACK statement, 9-1, II-58 to 
II-59 

HEXPRINT statement, II-60 

HEXUNPACK statement, 9-1, II-61 


Fee ee eee ee ieee rane eee er 


IF statement, 2-1, 6-1, 6-2, 
II-62 to II-63 
Image, definition of, Glossary-3 
Image (%) statement, 7-5 to 7-6, 
7-7 to 7-8, 8-12 to 8-14, 
II-64 to II-65 
use of, 7-7 to 7-8, II-64 to 
IE-65 
Indexed files, 8-1, 8-2 to 8-3, 
Glossary-3 
alternate keys, 8-2 
data blocks, 8-2 to 8-3 
index blocks, 8-2 ta 8-3 
mask, 8-2 
primary key, 8-2 
INIT statement, II-66 
INPUT mode, 8-1, Glossary-3 
INPUT statement, 7-2, II-67 to 
II-69 
Input/output statements, 7-1, 
7-2, 8-4 to 8-9, 9-2 
ACCEPT, 7-2, 7-8 to 7-15, II-4 
to II-9 
CLOSE, 8-7 to 8-9, II-24 to 
II-25 
DELETE, 8-12, II-40 
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DISPLAY, 7-1, 7-15, II-43 
GET, 8-12, II-53 
INPUT, 7-2, II-67 to II-69 
MAT INPUT, 9-2, II-84 to II-85 
MAT PRINT, 9-2, II-89 
MAT READ, 9-2, II-90 
OPEN, 8-7 to 8-9, II-107 to 
II-110 
PRINT, 7-1, II-124 to II-127 
PUT, 8-13, II-128 
READ, 8-12, II-130 to II-131 
REWRITE, 8-13, II-136 to II-137 
WRITE, 8-13, II-165 to II-166 
INT (integer) function, 4-7, 
II-70, II-97 
Integer calculation, 3-3, C-l 
Integer constants, 3-5 
Integer data, 4-13 to 4-14, 
Glossary-3 
Intrinsic functions, 8-15, 
Glossary-4 
FS, 5-6, 8-15, II-52 
KEY, 5-6, 8-15 to 8-16, II-71 
MASK, 5-6, 8-16, II-77 
SIZE, 4-8, 8-16, II-150 
IO mode, 8-8, Glossary—4 
IPACK keyword in OPEN statement, 


II-108 

K 

KEY function, 5-6, 8-15 to 8-16, 
II-71 

Keyword, definition of, 
Glossary-4 
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Label, definition of, Glossary-—4 

LEN (length of character string) 
function, 4-7, 5-7, II-72 

LET statement, 2-1, 4-1 to 4-2, 
II-73 

LGT (logarithm to base 10) 
function, 4-7, II-75, II-937 

Library, 1-4, 1-5, Glossary—4 

Line format, 2-2 to 2-3 

LINKER utility, 1-11, II-31, 
II-32 

Literal, definition of, 3-1, 
Glossary-—4 
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LOG (logarithm to base e) 
function, 4-7, II-76, II-97 
Logging on, 1-3 
Logical expressions, 5-10 to 
5-12, Glossary-—4 
evaluation of, 5-11 to 5-12 
Logical operators, 5-12 to 5-13 


M 


Machine language, 1-5 

MASK function, 5-6, 8-16, II-77 

MAT ASORT/DSORT, 9-3, II-79 to 
II-80 

MAT CON, 9-2, II-81 

MAT IDN, 9-2, II-83 

MAT INPUT, 9-2, II-84 to II-85 

MAT INV, 9-3, II-86 to II-87 

MAT PRINT, 9-2, II-89 

MAT READ, 9-2, II-90 

MAT REDIM, 9-3, II-91 

MAT TRN, 9-2, II-94 

MAT ZER, 9-2, II-95 


MAT =, 9-2, II-82 

MAT +, 9-2, II-78_ 

MAT -, 9-2, II-93 

MAT *, 9-2, II-88 

MAT ()*, 9-2, II-92 

Mathematical functions, II-96 to 
II-100 


Matrix, operations with 
addition, 9-2, II-82 
identity function, 9-2, II-83 
inverse function, 9-3, II-86 to 
II-87 
matrix multiplication, 9-2, 
II-88 
sort, 9-3, II-79 to II-80 
subtraction, 9-2, II-93 
transpose function, 9-2, II-94 
MAX (maximum value) function, 
4-7, II-98, II-101 
Menus, 1-3 
Command Processor, 1-3 
MIN (minimum value) function, 
4-7,  II-98, II-102 
‘Mixed mode arithmetic, 4-12 
Mixed mode, definition of, 3-4 
MOD function, 4-7, II-99, II-103 
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N 
NEXT statement, 6-1, 6-2, II-104 
NODISPLAY keyword in OPEN 
statement, II-108 
NOGETPARM keyword in OPEN 
statement, II-108 
null label, definition of, 
Glossary-4 
NUM (number of numeric characters 
in a character string) 
function, 4-8, 5-7, 5-8, 
II-105 
Number, definition of, 3-1 
Numeric 
constants, definition of, 
Glossary-4 
expressions, 4-4, Glossary—4 
functions (see Functions), 4-5 
4-11 
operators, 4-1 to 4-4 
Numeric data, 3-2 to 3-7 
Numeric functions with alpha 
arguments, 5-7 to 5-10 
LEN, 4-7, 5-7, II-72 
NUM, 4-8, 5-7, II-105 
POS, 4-8, 5-7, II-123 
VAL, 4-8, 5-7, 5-10, II-164 
Numeric terms, 4-14 to 4-15 
Numeric variables, 3-5 to 3-7, 
Glossary-4 
array, 3-6 
scalar, 3-6 
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Object file, 1-5 
Object program, 1-5, 1-12 
running, 1-12 
ON statement, 6-1, II-106 
One-dimensional array, 3-12 
column vectors, 3-12 
compared to two-dimensional 
array, 3-12 to 3-13 
lists, 3-12 
singly-subscripted arrays, 3-12 
vectors, 3-12 
OPEN statement, 8-7 to 8-9, 
II-107 to II-109 
Operators 
arithmetic, 4-2 to 4-3 
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assignment, 4-1 to 4-2 
assignment operator, 5-1 to 5-2 
concatenation operator, 5-2 to 
5-3 
logical, 5-12 to 5-13 
relational, 4-4 
relational operators, 5-3 to 
5-4 
OR logical operator, 5-11, 5-12, 
II-111 
Other numerical functions, II-97 
Output, 7-1 
DISPLAY statement, 7-1, 7-15, 
II-43 
PRINT statement, 7-1, II-124 to 
II-127 
OUTPUT mode, 8-8, Glossary—4 


P 


PACK statement, II-112 to II-113 

PI function, 4-5, II-100, II-122 

PIC, II-48, II-112, II-162 

POS function, 4-8, 5-7 to 5-9, 
II-123 

Print elements, II-125 to II-127 

Print files, 8-3, II-24, II-143, 
Glossary-4 

PRINT statement, 7-2 to 7-3, 
II-124 to II-127 

Printer output, 7-2 to 7-3 

expanded print, 7-3 
line feed, 7-3 

Prname, definition of, Glossary-—5 

Program development, 1-5 to 1-12 

Program Function keys (PF), 1-2, 
1-3, 6-7 

pseudovariable, definition of, 
Glossary-5 

PUT statement, 8-13, II-128 


R 


Random access, definition of, 
Glossary-5 
READ File statement, 8-12, 
II-130 to II-131 
READ statement, II-129 
relationship to DATA statement, 
II-129 
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relationship to RESTORE 
statement (see RESTORE), 
II-129 
Receiver, definition of, 3-2, 
Glossary-5 
Relational expression, definition 
of, Glossary—-5 
Relational operators, 5-3 to 5-4 
REM statement, 2-5, II-132 
Reserved words, 2-1, A-1 to A-2 
RESTORE statement, II-129, II-133 
RETURN CLEAR statement, 6-5, 
II-135 
Return code, 1-10 to 1-11 
RETURN statement, 2-1, 6-1, 6-2, 
6-5, II-134 
used with GOSUB, II-134 
REWRITE statement, 8-13, II-136 
to II-137 
restriction on use, II-136 
RND (random number) function, 
4-8, 4-9 to 4-10, II-138 
ROTATE[C] statement, 9-1, II-139 
ROUND function, 4-8, 4-10, II-140 
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scalar, definition of, Glossary-5 

scalar variable, definition of, 
3-6, Glossary-—5 

SEARCH statement, II-141 to 
II-142 

SELECT File statement, 8-5 to 
8-6, II-145 to II-147 

SELECT statement, 4-6, 7-1 to 
7-3, 7-16, II-24, II-143 to 
II-144 

Sequential access, definition of, 
Glossary-5 

SGN (signum) function, 4-8, 
II-97, I1I-148 

SHARED mode, 8-8, Glossary-5 

SIN (sine) function, 4-6, II-96, 
II-149 

SIZE function, 4-8, 8-16, II-150 

SKIP statement, 8-12, II-151 

Sort (matrix), 9-3, II-79 

ascending, 9-3, II-79 
descending, 9-3, II-79 
Sort statements, 9-3, II-79 
Source file, 1-5 
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Source program, 1-5 IF ... THEN ... ELSE, 6-1, 6-2, 
SPACE keyword in OPEN statement, II-62 to II-63 
II-108 Image (%), 7-5 to 7-6, 7-7 to 
Spaces, in statements, 2-3 to 2-4 7-8, 8-12 to 8-14, II-64 to 
SQR (square root) function, 4-8, II-65 
II-97, II-152 INIT, II-66 
Statement, definition of, 2-1 INPUT, 7-2, II-67 to II-69 
Statement labels, 6-2 to 6-3, LET, 2-1, 4-1 to 4-2, II-73 
Glossary-5 MAT ASORT/DSORT, 9-3, II-79 to 
Statements (see also I/0 II-80 


statements and individual 
entries) 
ACCEPT, 7-2, 7-8 to 7-15, II-4 


arithmetic (matrix), 9-2 to 9-3 


array dimensioning, 9-3 to 9-4 
assignment statement (matrix), 


9-2 

CALL, 6-1, 6-2, 6-8 to 6-17, 
II-21 

CLOSE, 8-7 to 8-9, II-24 to 
II-25 

COM, 3-14 to 3-15, 6-10, 6-13, 
II-26 


continuation, 2-4 to 2-5 

CONVERT, 9-1, II-27 to II-28 

COPY, II-29 

DATA, II-33 

data conversion, 9-1 

DEF, 4-11, II-35 to II-36 

DEF FN', 6-5, 6-7, II-37 

DELETE, 8-12, II-40 

DIM, 3-14 to 3-15, II-41 

DISPLAY, 7-1, 7-15, II-43 

EJECT, 2-6, II-44 

END, 6-1, II-45 

FMT, 7-5, 7-6, 7-7 to 7-8, 
8-12 to 8-14, II-47 

FOR, 6-1, 6-2, II-50 

FORM, II-51 

GET, 8-12, II-53 

GOSUB, 6-1, 6-2, 6-4 to 6-5, 
II-54 

GOSUB', 6-1, 6-2, 6-5 to 6-7, 
II-55 

GOTO, 2-1, 6-1, 6-2, II-56 

HEXPACK, 9-1, II-58 to II-59 

HEXPRINT, II-60 

HEXUNPACK, 9-1, II-61 

IF, 2-1, 6-1, 6-2, II-62 to 
II-63 

IF THEN, 2-1, 6-1, 6-2, II-62 
to II-63 
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MAT CON, 9-2, II-81 

MAT IDN, 9-2, II-83 

MAT INPUT, 9-2, II-84 to II-85 
MAT INV, 9-3, II-86 to II-87 
MAT PRINT, 9-2, II-89 

MAT READ, 9-2, II-90 


MAT REDIM, 9-3, II-91 


MAT TRN, 9-2, II-94 

MAT ZER, 9-2, II-95 

MAT =, 9-2, II-82 

MAT +, 9-2, II-78 

MAT -, 9-2, II-93 

MAT *, 9-2, II-88 

MAT ()*, 9-2, II-92 

matrix statements, 9-1 to 9-4 

multiple lines, 2-4 

NEXT, 6-1, 6-2, II-104 

ON, 6-1, II-106 

OPEN, 8-7 to 8-9, II-107 to 
II-110 

$PACK, II-114 to II-121 

PACK, II-112 to II-113 

PRINT, 7-1, II-124 to II-127 

PUT, 8-13, II-128 

READ, II-129 

READ File, 8-12, II-130 to 
II-131 

REM[ARK], 2-5, II-132 

RESTORE, II-129, II-133 

RETURN, 2-1, 6-1, 6-2, 6-5, 
II-134 

RETURN CLEAR, 6-5, II-135 

REWRITE, 8-13, II-136 to II-137 

ROTATE{C], 9-1, I1-139 

SEARCH, II-141 to II-142 

SELECT, 4-6, 7-1 to 7-3, 7-16, 
II-143 to II-144 

SELECT File, 8-5 to 8-6, II-145 
to ITI-147 

SKIP, 8-12, II-15l 

sort (matrix), 9-3 
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STOP, 6-1, 6-7, 7-16, II-153 
SUB, 6-9 to 6-16, II-155 
TITLE, 2-6, II-160 
TRAN, 9-1, II-161 
$UNPACK, II-114 to II-121, 
II-163 
UNPACK, II-162 
WRITE, 8-13, II-165 to II-166 
XOR, 5-11, 5-12, ITI-167 
STOP statement, 6-1, 6-7, 7-16, 
II-153 
STR (portion of string) function, 
5-6 to 5-7, II-154 
String dimension, definition of, 
Glossary-5 
SUB statement, 6-9 to 6-16, 
II-155 
Subroutines, 6-4 to 6-18 
CVDQ, 3-3, II-31 
CVQD, 3-3, II-32 
definition of, 6-4 
external, 6-8 to 6-18 
GOSUB, 6-4 to 6-5 
GOSUB', 6-5 to 6-7 
internal, 6-4 to 6-5 
Subscript, definition of, 
| Glossary-5 
Substring, definition of, 
Glossary-5 
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TAN (tangent) function, 4-6, 
II-96, II-158 
THEN keyword in IF statement, 
6-1, 6-2, II-62 to II-63 
TIME function, 5-6, II-159 
TITLE statement, 2-6, II-160 
TRAN statement, 9-1, II-161 
Trigonometric functions, 4-6, 
II-96 
Two-dimensional arrays, 3-12 to 
3-13 
doubly-subscripted arrays, 3-13 
matrices, 3-13 
tables, 3-13 
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UNPACK statement, II-162 


V 


VAL function, 4-8, 5-7, 5-10, 
II-164 
Variable, 3-1 
definition of, 3-1, Glossary-5 
Variable name, definition of, 3-1 
Volume, 1-4, Glossary-5 
VS Operating System, 1-4 to 1-5 


W 


Word, definition of, Glossary-6 
Workstation, 1-2 to 1-3, 7-3 to 
7-5 
Workstation I/0, 7-3 to 7-16 
FAC (Field Attribute 
Characters), 7-4 to 7-5 
scrolling, 7-4 
wraparound, 7-3 to 7-4 
WP files, 8-3, Glossary-—6 
WRITE statement, 8-13, II-165 to 
II-166 
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XOR logical operator statement, 
5-11, 5-12, II-167 


$ | 

$PACK data format, II-120 

$PACK statement, II-114 to II-121 

$UNPACK data format, II-120 

$UNPACK statement, II-114 to 
II-121, II-163 

2200 


2200 disk storage format, II-119 
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